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PREFACE 


This manual is for assembly language programmers who use the 
GCOS system service macro routines and macro calls in writing 
application programs. The manual describes the macro calls for 
monitor services, for using the file system, and for generating 
data structures. 


The manual also discusses Honeywell peripheral device 
drivers and how to write a user device driver. 


Section 1 concerns macro call syntax, register conventions, 
and addressing conventions. 


Sections 2, 3, and 4 briefly summarize and list macro calls 
for monitor services, for the file system, and for defining data 
structures, respectively. 


Section 5 describes in detail the use, structure, function, 
and error return codes for each macro routine and macro call, 
Some with examples. These descriptions are arranged alphabet- 
ically by function description name, according to the function 
description shown in column 2 of Table 1-1. 


Section 6 describes the GCOS 6 Honeywell device drivers for 
data transfer in system and applications programs with Level 6 
peripheral devices. 


Section 7 discusses trap handling for hardware and software 
traps. 


Appendix A describes various block data structures that are. 
related to certain macro routines. Appendix B discusses writing 
a user device driver. Appendix C summarizes register contents 
before and after execution of the system Service macro calls. 
Appendix D shows the ASCII and EBCDIC character sets. 
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SECTION 1 


INTRODUCING AND USING THE MANUAL 


This manual describes the function and use of GCOS 6 system 
service macro routines, used by the assembly language programmer 
to obtain monitor and input/output services and to build control 
structures, for applications programs. 


HOW TO USE THE MANUAL 


Table 1-1 is an alphabetic list of all macro calls and their 
functions, arranged alphabetically by macro call name (column 1). 


sections 2, 3, and 4 contain brief descriptions of the func- 
tional groupings for the macro calls, together with a list of the 
macro calls arranged alphabetically by function grouping. The 
lists also include the macro call names shown in column 1 of 
Table 1-1. Section 2 summarizes monitor servicesS macro calls, 
Section 3 the file system macro calls related to I/O services, 
and Section 4 the macro calls to generate and define system data 
structures. 


Section 5 describes the use, functions, Structures, and 
error return codes for all macro routines/calls, with one 
example for most. For easy reference, these detailed descrip- 
tions are arranged in alphabetic order by specific function, (see 
column 2 in Table 1-1). | 


This section also describes macro call syntax and register 
conventions. The Assembly Language Reference manual discusses 
the use of labels and address formats in detail. 


MACRO CALL SYNTAX 


Macro call syntax follows the conventions for assembly lan- 
guage. The first field of the macro call can have an optional 
label. If no label is used, at least one blank must precede the 
macro call. User-selected items of data in amacro call are 
Known aS arguments; these arguments are passed to a system ser- 
vice macro routine by the macro proceSsSor. 
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Within the called system service macro routine (which is . 3 
generalized to handle any set of data passed to it), the macro wee 
call arguments are associated with the service routine arguments 
-- the order of positional arguments in the macro call indicates 
the variables to which the data is applied. Thus, the order of 
your arguments must be the same as the positional arguments with- 
in the system service macro routine. Unless stated otherwise, 
omitted arguments. that precede an included argument must be 
indicated by the presence of a replacing comma for each omission. 
One or more spaceS must separate the macro call name from its 
arguments, with a comma between each argument. The horizontal 
tab character is equivalent to a space. A semicolon at the end 
of a line indicates that the next line is a continuation 
line. 


REGISTER CONVENTIONS AND CONTENTS 


Macro call arguments are often loaded into registers for 
access by the system services. An argument of a macro call can 
specify that the corresponding system service argument is either 
contained in memory or in a register. If an argument is omitted 
from the macro call the system assumes that the register normally 
used to provide the value or address to the system service rou- 
tine contains the requirec value or address. For this reason it 
is important to know how the system service routines use the re- 


gisters, as well as the conventions that exist for saving regis- 
ter contents.!' 


The system services use the following registers without pre- 
serving their contents:1 


Rl R7/ 
R2 B2 
R6 B4 


As a general rule, the system services do not alter the 
contents of the following registers: 


S Bl T S53 
I B 3 RDBR Ml through M7 
R 3 B5 Cr 
R4 Bo SI 
R5 B7 Sol 
S2 


When coding a macro call that uses a register whose con- 
tents are not preserved, ensure that the contents of the reg- 
ister are appropriate for each occurrence of the macro call. 


'The file system macro calls preserve the contents of all 
registers except Rl. B4 is the only register loaded by the file 
System macro calls. eo) 
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ADDRESSING CONVENTIONS 


Any macro call argument definition that specifies an argu- 
ment default of a specific register content will allow an argu- 
ment specification in the form =SRn or =SBn (n deSignates the 
register to be specialized for the system service routine) to 
denote that the register has been previously set to be the value. 
to be used. When a macro call argument description specifies 
that the location of a value or an address may be provided, any 
assembly-level address syllable format that is valid for the type 
of register being specialized can be used; i.e., the value (if 
less than or equal to two bytes) or address can be supplied as an 
immediate memory operand (IMO) address syllable form by prefacing 
the value or address with an equal sign (=). (The !label macro 
notation is used only to distinguish between LDB and LAB instruc- 
tions when specializing a base register.) 


For example, the SWAIT macro call has a single argument that 
specifies the location of the address of the request block to be 
waited on. This location must be placed in base register $B4. 
The value specified for this argument in the SWAIT macro call can 
take any of the following forms (among others): 


=label 


The label refers to the request block to be waited on. 
An IMO address syllable format will be used by the LDB 
instruction generated to load S$B4. 


label 


The label refers to a field that contains the address > 
of the request block to be waited on. A P+DSP address 
syllable format will be used by the LDB instruction 
generated to load S$B4. 


<label 


The label refers to a field that contains the address 
of the request block to be waited on. An IMA address 
Syllable format will be used by the LDB instruction 
generated to load $B4. 


=$B4 
Base register $B4 already contains the address of the 


request block to be waited on. No instruction will be 
generated to load SB4. 
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=$B 3 


Base register $B3 contains the address of the request 
block to be waited on. A register addressing address 
syllable will be used by the LDB instruction generated 
to load S$B4. 


$B3 


Base register $B3 contains the address of a field that 
contains the address of the request block to be waited 
on. A direct base addressing address syllable will be 
used by the LDB instruction generated to load S$B4. 


*SB3. 


Base register $B3 contains the address of a field that 
contains the address of a field that contains the 
address of the request block to be waited on. An in- 
direct base addressing address syllable will be used 
by the LDB instruction generated to load S$B4. 


$B3.$R2 


The address referred to by basSe register $B3 plus $R2 
contains the address of the request block to be waited 
on. An indexed base addressing address syllable will 
be used by the LDB instruction generated to load $B4. 


If the address syllable is preceded by an exclamation point 
(!) then the instruction generated is a LAB rather than an LDB. 
For example: 


!label 


The label refers to the address of the request block 
to be waited on. An effective address syllable format 
will be used by the LAB instruction generated to load 
SB4. 


'*label 


The label refers to a field containing the address of 
the the request block to be waited on. A "LAB S$B4, 
*label" instruction will be generated to load $B4. 


Thus, macro call "location address" arguments (which are to 
be loaded into base registers) can refer to the location of the 
address of the data or data structure or can refer to the address 
of the data or data structure. In the first case (location of 
address), the macro call loads the S$Bn register through an LDB 
instruction, thus requiring that the "location address" values 
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in the macro call arguments be the label of a location where the 
address of the actual argument structure is located. In the 
second case (address), the macro call loads the effective address 
of the argument structure into $Bn directly (through a LAB in- 
Struction) when the first argument is a label and is preceded by 
an exclamation point (!) character. 


For Example: 


FIBPTR DC <FIB 


FIB RES V 16 


Smacro FIBPTR =>LDB S$B4,FIBPTR 


Smacro !FIB 


>LAB $B4,FIB 


REGISTER CONTENTS AT TASK ACTIVATION 


a nt ed 


When a task is activated, the contents of registers $B4, 
SB5, and S$B7 are the following: 


Register SB4: Address of the task request block 


Register S$B5: Address of the system-Supplied termination 
routine (see the return (SRETRN) macro call) 


Register $B7: Address of the parameter block containing 
the request block argument list 


REGISTER CONTENTS AT INITIAL TASK ACTIVATION 


i eat et eta ne nee ece enter cetera ne ati tena ei eee 


The M registers are set up as follows: 


When each task starts, the system establishes the following de- 
fault values Ml, M3, M4, and M5: 


M1 = 00 Trace trap and all R-register overflow traps 
disabled. 


M3 = 00 CIP overflow trap and truncation trap disabled; 


CIP is under direct CPU firmware control (i.e., 
not in software test mode). 
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M4 = 03 Truncation mode in effect. Scientific accumula- 
tors $S1 and $S2 and associated memory operands 
are two words long; $S3 and associated memory 
operands are four words long. 


M5 = 20 Significance error trap enabled; exponent overflow 


and precision error traps disabled. 


Contents of these registers can be modified with the assem- 
bly language instruction MTM. 


If the task is in an online task group, then the privileged 
bit in the S-register is set on. If the task is not in an online 
task group, the privileged bit is not set. 


RETURN STATUS CODES IN SR1 REGISTEER 


The descriptions of the macro calls in Section 5 include 
lists of status codes returned in register S$R1, together with an 
explanation of each code. These lists, while extensive, are not 
intended to include every possible status return or explanation 
for each macro call. See the System Messages manual for a list 
of all $R1 return status codes, corresponding messages, and added 
definitions. 


SYSTEM SERVICE MACRO CALLS AND FUNCTION CODES 


Table 1-1 contains an alphabetic list, by macro call name, 
of the macro calls summarized in Sections 2, 3, and 4, and de- 
scribed in Section 5. The list includes the function codes 
associated with each macro call (data structure generation macro 
calls do not have function codes). The first two digits of the 
function code designate the major function, and are used by the 
macro call trap-handling routine to locate the entry point of the 
appropriate system service routine. The last two digitS are a 
subfunction code used by the system service routine to provide 
the requested subfunction. When a macro call is executed, it 
generates the following: 


MCL 
DC zZ'mmss' 


where mm is the 2-digit major function code and ss is the 2-digit 
subfunction code. The function codes are provided for informa- 
tion only; they will appear in program listings and dumps. 


LOCATION OF MACRO ROUTINES 


The macro routines are located either on cartridge disk or 
on storage module in a library named >LDD>MACRO>SEXEC LIB. On 
diskette they are located in A“ZSYS02>LDD>MACRO>EXEC LIB. See the 


Assembly Language Reference manual. 
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Table 1-1. System Service Macro Calls 


Function 
Group 


Function 
Function Description Code 


Macro 
Call Name 


SABGRP 


SABGRQ 


SACTID 


SACT VG 


SASFIL 


SBUID 


SCANRQ 


SC IN 


SCLFIL 


SCLPNT 


SCLRSW 


SCMDLN 


SCMSUP 


SCNCRQ 


SCNSRQ 


Abort group 


Abort group request 


Account identifier 


Activate group 


Associate file 


Bound unit identification 


Cancel request 


Command in (read command- 
in file) 


Close file 


Clean point 


Clear external switches 


Command line, process 


Console mesSage suppression 


Cancel clock request 


Cancel semaphore request 


1055-1057 


0C13 


OB02 


0C08 


0902/0903 


0501 


0601 


Task group 
control 


Task group 
control 


Identifica- 
tion and 
information 


Task group 
control 


File manage- 
ment 


Identifica- 
tion and 
information 
Task control 
Standard 


system file 
I/O 


File manage- 
ment 
Task control 


External 
switch 


Task control 


Operator 
interface 


Clock 


Semaphore 
handling 
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Table 1-1 (cont). System Service Macro Calls 


Function 
Group 


Function 
Code 


Macro 


Call Name Function Description 


SCRBD 


SCRDIR 


SCRFIL 


SCRGRP 


SCROAT 


SCRPSB 


SCRTSK 


SCWDIR 


SDFSM 


SDLGRP 


SDLREC_ 


SDLTSK 
SDSDV 


SDSFIL 


SDSTRP 


Clock request block 


Clock request block offsets 


Create 


Create 


Create 


Create 


Create 


directory 


file 


group 


overlay area table 


file parameter 


Structure block - offsets 


Create 


Change 


Define 


Delete 


Delete 


Delete 


task 


working directory 


semaphore 


group 


record 


task 


Disable device 


Dissociate file 


Disable user trap 


0C02/0C03 


10B0 


0604 


OD04 


1130/1131 


0c04 
0202 


1015 


OA02 


genera- 


struc- 
genera- 


manag e- 
manag e- 
group 


control 


Overlay 
handling 


Data struc- 
ture genera- 
tion 


Task control 


File manage- 
ment 


Semaphore 
handling 


Task group 
control 


Data mange- 
ment 


Task control 
Physical I/0 


File manage- 
ment 


Trap handling 
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Macro 


Call Name 


(1) 


SELEND 


SELEX 


SELGT 


SELST 
SENDV 
SENTRP 


SEROUT 


SEXTDT 


SEXTIM 


SFIB 


SGDTM 


SGIFAB 


SGIFIL 


SGIKDB 


SGIPSB 


Function Description 
(2) 
Error logging, end 


Error logging information, 
exchange 


Error logging information, 
get 


Error logging, start 
Enable device 
Enable user trap 


Error output file - write to 


External date/time - convert 
to 


External time -—- convert to 
File information block - 
create or change 

Get date/time 

Get file information, file 
attributes block - offsets 


Get file information 


Get file information and 
create file, key descriptor 
block - offsets 


Get file information, pa- 
rameter structure block - 
offsets 


Table 1-1 (cont). System Service Macro Calls 


Function 


Group 
(4) 


Physical 


Physical 
Physical 


Physical 


Physical I/0 
Trap handling 
Standard 
system file 


I/O 


Date/time 2K 


Date/time 


Data struc- 
ture genera- 
tion 


Date/time 


Data struc- 
ture genera- 
tion 


File manage- 
ment 


Data struc-— 
ture genera-— 
tion 


Data struc- 


ture genera-— 
tion 
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Table 1-1 


Macro 
Call Name 


SGTFIL 


SGT PSB 


SGWDIR 


SHDIR 


SINDTM 


SIORB 
SIORBD 
SMAC PT 
SMCMG 
SMGCRB 


SMGCRT 


(cont). 


Function Description 
Get memory; get available 
memory 


Get file 


Get file, parameter struc- 
ture block - offsets 


Get working directory 


Home directory, return 


Internal date/time - 
convert to 


Input/output request 
block 


Input/foutput request 
block offsets 


Message group, accept 


count 


Message group, 


Message group control 
request block 


Message group control request 


block offsets 


System Service Macro Calls 


Function 
Code 


0402/0403 


1020 


Function 


Group 


Memory allo- 
cation 


File manage- 
ment 


Data struc- 


ture genera- 
tion 


File manage- 
ment 


Identifica- 
tion and in- 
formation 


Date/time 


Data struc- 
ture genera- 
tion 


Data struc— 
ture genera- 
tion 


Intergroup 
message fa- 
cility 


Intergroup 
message 
facility 


Data struc 
ture genera- 
tion 


Data struc- 
ture genera- 
tion 
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wf 


Macro 


Call Name 


(1) 


SMGIRB 


SMGIRT 


SMGRRB 


SMGRRT 


SMINIT 


SMODID 


SMRECV 


SMSEND 


SNPROC 


SNUIN 


SNUOUT 


Table 1-1 


(cont 


Function De 
(2) 


Message group 


request block 


Message group 
request block 


Message group 
block | 


Message group 
block offsets 
Message group, 
Mode identific 
Message group, 
Message group, 


Message group, 


New process 


New user input 


redefine 


). System Service Macro Calls 


scription 


initialization 


initialization 


offsets 


recovery request 


recovery request 


initiate 


ation 


receive 


send 


terminate 


file - 


New user output file - 


redefine 


1502 


1403 


1503 


1505 


1504 


OD OB 


0806 


0807 


genera- 


struc-— 
genera- 


struc- 
genera- 


struc- 
genera- 


Intergroup 
message 
facility 


Identification 
and informa- 
tion 


Intergroup 
message facil- 
ity 


Intergroup 
message facil- 
ity 


Intergroup 


message facil- 
ity 


Task group 
control 


Standard 
system file 
1 Ae) 


Standard 
system file 
I/O 
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Macro 


Call Name 


(1) 


SOPFIL 


SOPMSG 


SOPRSP 


SOVEXC 


SOVLD 


SOVRCL 


SOVRLS 


SOVRSV 


SOVST 


SOVUN 


SPERID 


SPRBLK 


SRBADD 


SRDBLK | 


SRDREC 


Table 1-1 (cont). 


Function 
Code 


Function Description 
| (3) 


(2) 
Open file 
Operator information 
message —- display only 


Operator response 
message -— display/respond 


Overlay, execute 


Overlay, load 


Overlay release, wait, and 
recall 


Overlay area, release 


Overlay area reserve, and 
execute overlay 


Overlay status 
Overlay, unload 


Person identification 


Parameter block 


Return request block 0107 


address 


Read block 1200-1204 


Read record 1110-1116 


System Service Macro Calls 


Function 
Group 
(4) 


1050/1051;File manage- 


ment 


Operator 
interface 


Operator 
interface 


Overlay 
handling 


Overlay 
handling 


Overlay 
handling 


Overlay 
handling 


Overlay 
handling 


Overlay 
handling 


Overlay 
handling 


Identification 
and informa- 
tion 

Data struc- 
ture genera- 
tion 


Request and 
return 


Storage 
management 


Data manage- 
ment / 
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Table 1-1 (cont). System Service Macro Calls 
Macro Function Function 
Call Name Function Description Code Group 
External 
switch 


SRDVAT Reset device attention Physical I/O 


SRETRN Return sequence - establish Request and 
return 


SRLDIR Release directory File manage- 
ment 


SRLFIL Release file 1035 File manage- 
ment 


SRLSM Release semaphore 0603 Semaphore 
handling 


SRLTML Release terminal 1704 Terminal 
Function 


SRM EM Return memory; return 0404/0405 | Memory 
partial block of memory allocation 


SRMFIL Remove file | 1025 File manage- 
ment 


SRNFIL Rename file/directory 1040 File manage- 
ment 


SRPTER Report error condition OFOO/OFO1] | Error hand- 
ling 


SROBAT Request batch execution OE0O0 Batch 
SROCL Request clock 0500 Clock 


SROGRP Request group OD00 Task group 
control 


SROQIO Request I/O transfer 0200 Physical I/O 


SRQSM Request semaphore 0600 Semaphore 
handling 


SROTML Request terminal _ | 1703 Terminal 
7 Function 
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Macro 


Call Name 


SRS VSM 


SRWREC 


SSDL 


SSETSW 


SS PGRP 


SSPTSK 


SSRB 


SSTMP 


SSTTY 


SSUSPG 


SSUS PN 


SSYSID 


Table l1-l 


(cont). 


Function Description 


Request task 


Reserve semaphore 


Rewrite record 


Set dial 


Set external switches 
Spawn group 
Spawn task 


semaphore request block 


Semaphore request block 
offsets 


Status memory pool 
Set terminal file 
characteristics 


Suspend group 


Suspend for interval; sus- 


pend until time 


System identification 


Test completion status 


1-14 


Function 
Code 


1140/1141 


1B00 


OBOl 


ODO5 


0C05/0C06 


0406 


1045 


0D08 


0502/0503 


1404 


Function 
Group 


Task control | 


Semaphore 
handling 


Data manage- 
ment | 


Communica- 
tions 


External 
Switch 


Task group 
control 

Task control 
Data 


ture 
tion 


struc- 
genera- 


Data 
ture 
tion 


struc-— 
genera- 


Memory al- 


location 


File manage- 
ment 


Task group 
control 


Clock 
Identifica- 
tion and in- 


formation 


Request and 
return 
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System Services Macro Calls on 


te 


Macro 
Call Name 


(1) 


STIFIL 


STOFIL 


STRB 


STRMRQ 


STR PHD 


SUSIN 


SUSOUT 


SUSRID 


SWAIT 


SWAITL 


SWIFIL 


Table 1-1 


(cont). 
Function 
Function Description Code 
(2) (3) 
File information block - 
offsets 


Task group input 


Test file for input 


Test file for output 


Task request block 


Task request block offsets 


Terminate request 0103/0104 


Trap handler connect OA00 


User input file - read 0800 


output file - write 


identification 


Wait for operation 
complete 


Wait on request list 


Wait for file input 


System Service Macro Calls 


Function 
Group 
(4) 


Data sStruc- 
ture genera-— 
tion 


Identifica- 
tion and in- 
formation 

File manage- 

ment 


File manage- 
ment 


Data struc- 
ture genera- 
tion 


Data struc- 
ture genera- 
tion 


Request and 
return 


Trap handling 


Standard 7 
system file 
Ifo 


Standard 
system file 
I/O 


Identifica- 
tion and 
information 


Request and 
return 


Request and 
return 


File manage- 
ment 
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Table 1-1 (cont). System Service Macro Calls 


Function Function 


Call Name Function Description > Code Group 


(1) 


SWLIST 


SWOFIL 


SWRBLK 


SWRREC 


SWTBLK 


SXPATH 


(2) (3) (4) 


Wait list |Data struc- 
ture genera- 
tion 


Wait for file output 1065 File manage- 
ment 


Write block 1210/1211 | Storage 
management 


Write record 1120/1126 | Data manage- 
ment 


Wait block 1220 Storage 
management 


Expand pathname 10D 0 File manage- 
ment 


TASK REQUEST QUEUES 


The task manager controls the scheduling and synchronization 
of tasks, and uses the following data structures. 


O 


oO 


Logical Resource Number (LRN) - An LRN provides a logical 
task identifier. You assign an LRN to an application 
task when the application is designed; you assign an LRN 
to a system device driver task at configuration. Its 
value is from 0 through 252. 


Logical Resource Table (LRT) - An LRT associates each LRN 
with a specific resource control table (RCT). An LRT is 
created for each user task group and contains an entry 
for each LRN specified in the task group. Each entry in 
the LRT points to an RCT that uniquely identifies one of 
the task group's tasks. 


The system has one LRT to associate each configured de- 
vice with an LRN. The LRT contains an entry for each 

LRN identified to the Configuration Load Manager at sys- 
tem Startup. Each entry in the LRT points to an RCT that 
uniquely defines the configured device. 
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o Resource Control Table (RCT) - A separate RCT is built 
for each task or device. Each RCT contains the physical 
priority level number dedicated to that task or device. 
In addition, each device RCT contains the device-specific 


characteristics that uniquely describe that device. 


o Reguest Block (RB) - The RB is the basic control struc- 
ture that embodies a specific request for the execution 
of a task. An RB contains the arguments of a task re- 
quest; it provides the medium of communication between 
the requesting and requested tasks. Separate RB formats 
exist for tasks and devices, but the control fields used 
by the task manager are common to both formats. You may 
extend the RB to include application-specific information 
to be passed between the requesting and requested tasks. 


o Request Queue - The request queue is a first-in/first-—out 
queue of request blocks maintained by the task manager in 
order to serialize requests for task services. A sepa- 
rate request queue is maintained for each task. 


o Task Control Block (TCB) - A TCB is the system control 
structure for a task and includes the interrupt Save area 
(ISA). When a task is interrupted by a task with a 
higher priority level, the contents of the ISA are stored 
in the task control block of the interrupted task. 


The task manager controls tasks by manipulating request 
blocks in task request queues. Using the logical resource number 
provided in a request block, the task manager consults the logi- 
cal resource table to locate the TCB of a requested task; the 
mechanism is shown in the diagram below. 


LOGICAL RESOURCE TABLE 


ae LOGICAL 
RESOURCE 

POINTER NUMBER 
L 3 _ 


RESOURCE CONTROL TABLE 


PRIORITY 
LEVEL 
NUMBER 


A request for a task causes a request block to be placed in 
the request queue for the requested task. When the requested 
task terminates, the task manager removes the request block from 
the top of its request queue and posts its completion. If 
desired, one task may wait for the completion of the requested 
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task; the waiting task is suspended until the requested task 
Signal its completion to the task manager, which will re- 
activate the waiting task. In the meantime, other tasks may use 
the level of the waiting task. 


TCBS representing task code are assigned to execute on phys- 
ical priority level of the central processor. One or more TCBS 
may be assigned to use a level, and will be queued awaiting 
availability if there is a request for the task. When the TCB 
heading the level queue terminates with an empty request queue or 
is temporarily suspended by the system, the next TCB on that 
level moves to the head of the level queue. The system may 
suspend a task while processing a system service call, €.g., 
fetching a system overlay; the task may also explicitly suspend 
by performing a wait or suspend operation. When a suspended task 
reactivates, its TCB is placed at the end of the appropriate 
level queue. 


The following sequence of events illustrates an example of 
request queue manipulation as one task (e.g., task A, identified 
as logical resource number 1 at priority level 7) requests the 
execution of another task (e.g., task B, identified as logical 
resource number 2 at priority level 10, a lower priority level) 
and later waits for completion of the requested task. 


1. Task A requests task B (specifying logical resource 
number 2 in the request block). The task manager places 
this request block at the end of the request queue for 
Task B which executes at priority level 10. See Diagram 


dg 
ANOTHER REQUEST 
REQUEST BLOCK 
BLOCK FROM TASK A 
TASK B REQUEST QUEUE 
Diagram 1 -—- Request Block From Task A is Queued in 


Reguest Queue for Task B 
2. Task A issues a wait call, indicating that it wishes to 


be suspended until its request for Task B is completed. 
Task A iS now suspended. 
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ee 3. Task B runs and terminates relative to the first request 

( block in the request queue for the task. As Task B 
terminates, the first request block is removed from the 
request queue for the task. See Diagram 2. The TCB for 
Task B on priority level 10 remains active because 
another request block (the one generated by Task A) 
exists in its request queue. 


ANOTHER 
REQUEST 
BLOCK 


REQUEST 


BLOCK 
FROM TASK A 


wer EEE 


TASK B REQUEST QUEUE 


Diagram 2 - First Request Block is Dequeued as Task B 
Terminates Relative to It 


4, Task B runs and terminates relative to the request block 
generated by Task A. Task A, which was waiting for this 
event, is now reactivated, The request block generated 
by Task A is removed from the reguest queue for priority 
level 10. Task A will resume execution when priority 
level 7 becomes the highest active level, and the Task A 
TCB again reaches the beginning of the level 7 TCB 
queue. 
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SECTION 2 


MONITOR SERVICE FUNCTIONS 


The Monitor service macro routines Summarized and listed in 
this section provide access to system service functions. The 
macro routines/calls are arranged and discussed within and in the 
order of these functional groups (See column 4 in Table 1-1): 


Batch Overlay handling 

Clock Physical I/0O 
Communications Request and return 
Date/time Secondary user terminal 
Error handling Semaphore handling 
External switches Standard system file I/O 
Identification and information Task control 

Memory allocation Task group control 


Message facility (intergroup) Trap handling 
Operator interface 


Each macro routine/call is described in detail in Section 5, 
in the alphabetic order of its function description (column 2 of 
Table l-l). 

BATCH FUNCTIONS 

The macro call for batch functions facilitates program 
execution in a way that requires no personal interaction with 
the system. To use the batch functions, prepare a file that is 
to act as the command input file and the user input file. All 
commands and program input are read from this file by the batch 
task group when your request executes. 

The macro routine/call is: 

o Request batch execution SRQBAT 


Section 5 describes this macro call in detail. 
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CLOCK FUNCTIONS 


The macro calls for clock functions allow user control of 
task execution according to an elapsed time period. These macro 
calls use the clock manager, a system component whose primary 
function is initiating task execution based on the passage of 
time. 


The clock manager services interrupts from the real-time 
clock. At each interrupt, the clock manager ascertains whether 
the time interval associated with a request to initiate execution 
of the task has been satisfied. Based on information contained 
in the clock request block (see Appendix A), the system will: 


Activate a task 
Schedule an indicated request block 
o Release a semaphore 


omne) 


The clock macro calls act to: 
o Connect a clock request block to the timer queue 
o Disconnect a clock request block from the timer queue 


o Suspend the issuing task until an interval of time has 
passed 


o Suspend the issuing task until a particular date/time 
The clock function macro routinesS/calls are: 


Cancel clock request S$CNCRO 


ro) 

o Request clock SROCL 
o Suspend for interval SSUSPN 
o Suspend until time SSUS PN 


section 5 describes these macros in detail and also the 
macro SCRB (clock request block) for generating a clock request 
block. 
COMMUNICATIONS FUNCTIONS 

The macro call for communications functions allows you to 
set a telephone number to be used for automatic dialing. The 
macro routineS/call is: 

o Set dial 7 SSDL 


The Communications Processing manual describes communica- 
tions processing. 


section 5 describes the above macro in detail. gees 


Na a 
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DATE/TIME FUNCTIONS 

The macro calls for date/time functions allow access and use 
of the internal date/time value maintained by the system, and 
conversions of date/time values for internal to external formats, 
and vice versa. Specifically, the macro calls provide the task 
with the means to: 

o Obtain the current internal date/time value 


o Convert the internal date/time value to external date/ 
time format | 


Oo Convert the internal date/time value to external time 
format 


o Convert an external date/time value to internal format 


The date/time macro routines/calls are: 


External date/time - convert to SEXTDT 
External time — convert to SEXTIM 
Get date/time SGDTM 

Internal date/time - convert to SINDTM 


Section 5 describes these macros in detail. 


ERROR HANDLING FUNCTION 


The macro for error handling enables you to report error 
conditions and to add error text. | 


The error handling macro routine/call is: 
Report error condition SRPTER 
section 5 describes it in detail. 


EXTERNAL SWITCH FUNCTIONS 


A task group, by uSing external switch function macro calls, 
can control its own execution by modifying its own external 
Switches. An external switch operates much like a hardware 
switch on an operator's control panel. External switches may be 
set and cleared with the MSW (modify Switches) command, or inter- 
nally with the SSETSW and SCLRSW macro calls. 


A separate external switch word is associated with each task 


group. Each bit in the word is an external switch. Thus, each 
task group can use 16 switches. A user program can contain 
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instructions or statements to interrogate the settings of one or 
more of these switches. The program can then use these settings 
to control its execution logic. 


The macro calls allow you to: 
o Set switches 
o Clear Switches 


o Read the current values of the switches 


The macro routines/calls are: 


Clear external switches SC LRSW 
Read external switches SRDSW 
Set external switches SSETSW 


Section 5 describes these macros in detail. 


IDENTIFICATION AND INFORMATION FUNCTIONS 
The macro calls for identification and information make 


available the following information concerning the current task 
Or task group. 3 


Function Macro Call 
Home directory pathname SHDIR 
Bound unit identification SBUID 
System identification SSYSID 
Task group account identification SACTID 
Task group input file name STGIN 

Task group mode identification SMODID 
Task group person identification SPERID 
Task group user identification SUSRID 


Section 5 describes these macro in detail. 
MEMORY ALLOCATION FUNCTIONS 


The macro calls for memory allocation functions allow you to 
dynamically obtain memory from the task group's memory pool, to 
return this memory when it is no longer needed, and ascertain the 
amount of memory available in a specified pool. 


The macro call that allocates a memory block has two forms: 
one form allowsS you to obtain a memory block of the specified 
size only; the other allows you to obtain the largest existing 
contiguous memory block if a block of the specified size cannot 
be found. The macro call that returns a memory block also has 
two forms: one form allows you to return an entire memory block; 
the other allows you to return a specified part of the block. 
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The macro routineS/calls are: 


Get memory; get available memory SGMEM 


Return memory; return partial SRMEM 
block of memory 


Status memory pool SS TMP 


Section 5 describes these macros in detail. 


MESSAGE FACILITY FUNCTIONS 


The message facility allows two task groups, using assembly 
language code, to have online communication between them by 
sending a message (one or more records) through message queues 
called mailboxes. A message group is a set of records that con- 
stitute a message sent through a mailbox. 


The message facility macro calls are issued by the task 
groups to perform message group and message functions. (The 
Mod 400 System Concepts manual describes the message facility.) 


The intergroup message facility macro calls have the follow- 
ing functions: 


‘e) 


oO 


oO 


O 


Open the send function of the message facility (accept) 
Ascertain number of messages in the mailbox 


Open the receive function of the message facility 
(initiate) 


Terminate the message group 
Receive the data 


send the message data 


The message facility macro calls are: 


Message group, accept SMAC PT 
Message group, count SMCMG 
Message group, initiate SMINIT 
Message group, terminate SMTMG 
Message group, receive SMRECV 
Message group, send SMSEND 


Section 5 describes these macros in detail. 
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OPERATOR INTERFACE FUNCTIONS 


The macro calls for operator interface functions enable 
tasks to communicate with the operator terminal by: 


o Displaying an information message on the operator 
terminal 


o Sending a message to the operator terminal and receiving 
a response 


o Activating or deactivating console suppression, i.e., 
Suspend or restore issuance of messages to the operator 
terminal for the issuing task group 


The macro routines/calls are: 


Console message suppression SCMSUP 
Operator information message SOPMSG 
Operator response message SOPRSP 


The SOPMSG and SOPRSP macro calls require input/output re- 
quest blocks (IORB's), which can be generated by the $IORB macro 
call (see Sections 4 and 5 and Appendix A). 


Section 5 describes the operator interface macros in detail. 
OVERLAY HANDLING FUNCTIONS og 


Overlays may be loaded at a fixed displacement from the base 
of the root-segment at link time, or if "floatable," into a block 
of memory allocated explicitly by the user or implicitly by the 
system. . 


The user may create a set of overlay areas and have the sys- 
tem load floatable overlays into them, managing the availability 
of free areas, and locating available copies of requested 
overlays. 

The macro routinesS/calls are: 


Overlay, release, wait, and recall SOVRCL 


Overlay area, release SOVRLS 
Overlay area reserve, and execute overlay SOVRS V 
Create overlay table | SC ROAT 
Overlay, execute SOVEXC 
Overlay, load SOVLD 
Overlay status | SOVST 
Overlay, unload SO VUN 


Section 5 describes these macro in detail. 
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PHYSICAL I/0 FUNCTIONS 

The macro calls described in this subsection allow you to 
interact with device drivers. If direct access to devices is not 
a requirement, use the File System macro calls. 

The physical I/O macro calls allow you to: 

o Request input and output 


o Disable’ a device when an attention interrupt occurs 


Oo Set the resource control table (RCT) of a device to the 
enable status 


o Turn off the attention status indicator in the RCT of the 
specified device 


see Section 6 for a complete description of Level 6 physical 
I/O functions, including details on device drivers and resource 
control tables. 


The macro routines/calls for physical I/O are: 


Disable device on attention SDSDV 
Enable device SENDV 
Reset device attention SRDVAT 
Request I/O transfer SRQIO 


Another group of macro calls associated with physical I/O 
function codes are the error logging macro calls which: 


o Activate error logging for a device 


o Insert current values of error logging information in the 
user's error log structure 


o End error logging and store logging information in user's 
error log structure 


’ 


o Verify and save user error logging structure. 


The macro calls for error logging are: 


Error logging, start SELST 
Error logging information, get SELGT 
Error logging, end SELEND 
Error logging information, exchange SELEX 


Section 5 describes these macros in detail. 
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REQUEST AND RETURN FUNCTIONS \ 


The macro calls for request and return functions enable you 
to control requests for tasks and to provide a Standard return 


sequence for called subroutines. Specifically, the macro 
routines are used to: : 


Terminate the current execution of a task 

Wait for the completion of another task 

Wait for the completion of any of a number of svanes 
Test for the completion of an event 

Return the address of a request block 

Issue a common return sequence for called subroutines 


000000 


The macro routines/calls are: 


Return request block address SRBADD 
Return SRETRN 
Terminate request STRMROQ 
Test completion status STEST 
Wait for operation to complete SWAIT 
Wait on request list SWAITL 


Section 5 describes these macros in detail. 


Sections 4 and 5 describe the macro routines for generating 
request blocks. Appendix A shows request block formats. 


SECONDARY USER TERMINAL FUNCTIONS 


The macro calls for secondary terminal functions pertain to 
a task group's secondary user terminal, which is defined aS a 
terminal given to a task group by the listener component when a 
a secondary login is performed at that terminal. This occurs 


provided the task group has an outstanding request for a second- 
ary user terminal. 


The macro calls for secondary user terminal functions 
permit: 


o The task group to request a secondary terminal. 
o The task group to release a secondary terminal. 


o The task group to cancel a previous request from the 
issuing group. 


f | 
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ys. 


The appropriate macro calls are: 


Request terminal SROTML 
Release terminal SRLTML 
Cancel request SCANROQ 


Section 5 describes these macros in detail. 


SEMAPHORE FUNCTIONS 


A semaphore is a mechanism for coordinating the use of re- 
Sources within task groups. Semaphores are unique to a task 
group and once defined, are available only to the tasks within 
that group, to control access to multiple resources and control 
multiple requests for the same resource. 


A semaphore is defined for each resource to be controlled 
and given a 2-character ASCII semaphore name, which is a system 
symbol recognized by the Monitor. Every requestor of a resource 
whose use must be coordinated issues appropriate Monitor calls 
to the named semaphore to request or release the resource. The 
task that defines the semaphore assigns the Semaphore's initial 
value. The Monitor maintains its current value to coordinate 
requestors of the resource being controlled. A requestor obtains 
use of a resource if the semaphore value is greater than zero at 
the time of the request. A requestor is either suspended waiting 
for the resource or notified that no resource is available if the 
value iS zero or negative. 


Monitor service macro calls are used to: 
o Define a semaphore and give an initial value. 


o Reserve a semaphore-controlled resource; this macro call 
SubtractsS a resource, or Signals a waiter for the re- 
source i.e., it decrements the current-value counter. 


o Release a semaphore-controlled resource; this macro call 
adds a resource, or activates the first waiter on the 
Semaphore queue; i.e., it increments the current-value 
counter. 


o Request the reservation of a Semaphore-controlled re- 
Source; this macro call queues a request block (SRB) if 
the resource is not available. This macro call decre- 
ments the current-value counter. 


Oo Remove a specified semaphore request block from its 
semaphore request queue. 


A semaphore is a gating mechanism, and the initial value 
given to it depends upon the type of control to be exercised. 


2-9 | CB08 


For example, assume that you want to restrict access to a Se 
particular resource to a one-user-at-a-time order. 


1. Task A defines a semaphore by issuing the macro call: 
SDFSM ZZ 


Omission of the value parameter causes the initial value to 
be set to l. 


2. Task B now issues a SRSVSM call; the counter is decre- 
mented to 0, Task B gets the resource for itself knowing 
that no other task using the Semaphore mechanism is 
uSing or can obtain the resource. 


3. Task C issues a SRSVSM call; the counter is decremented 
to -l, Task C is suspended (Task B is still using the 
resource). 


4. Task B issues a SRLSM when it finishes with the re- 
source; the counter is incremented to 0, Task C now gets 
the resource. After the SRLSM for Task C, the value is 
l again. 


Use of resources by more than one user at a time can be ar- 
ranged by adjusting the initial value of the semaphore, e.g., an 
initial value of 2 allows two users, a value of 4 allows four 
users, and so on, depending on the nature of the resource and its 
intended use. 


If it is undesirable for a task to be suspended while a re- 
source is in use, the SRQOSM macro call can be used instead of 
SRSVSM to reserve a resource. SRQSM is an asynchronous reserva- 
tion request (SRSVSM is a synchronous request) which causes a 
request block to be queued for the resource, so that the issuing 
task can do other processing before the needed resource is 
available. | 


The macro routines/calls for semaphore handling are: 


Cancel semaphore request SCNSROQ 
Define semaphore SDFSM 
Release semaphore SRLSM 
Request semaphore SROSM 
Reserve semaphore SRS VSM 


Section 5 describes these macros in detail. 


STANDARD SYSTEM FILE I/O FUNCTIONS 


ce a a a 


The macro calls for standard system file I/O functions make a 


the standard system files (command-in, user-in, user-out, and B 
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error-out) available to a task group. Other macro calls shown 
below allow the task to redefine the user-in and user-out files. 
Specifically, the macro routines enable you to: 


Read the next record from the command-in file 
Write the next record to the error-out file 
Read the next record from the user-in file 
Write the next record to the user-out file 
Redefine the user-in file 

Redefine the user-out file 


000000 


The macro routinesS/calls are: 


Command in (read command-in file) SC IN 
Error output file SEROUT 
New user input file SNUIN 
New user output file SNUOUT 
User input file SUSIN 
User output file SUSOUT 


section 5 describes the macros in details. 
TASK CONTROL FUNCTIONS 

The macro calls for task control allow you to: 

o Create, request, spawn, and delete a task 

Oo Process command lines 


o Unlock locked records for all files attached to the 
task group (clean point) 


Some macro calls involve the use of request blocks. Sec- 
tions 4 and 5 discuss and describe macro calls that generate re- 
quest blocks; Appendix A shows the format of the request blocks. 


Macro routines/calls for task control are: 


Cancel request SCANRQ 
Clean point SC LPNT 
Command line, process SCMDLN 
Create task SCRTSK 
Delete task SDLTSK 
Request task SROTSK 
Spawn task SS PTSK 


Section 5 describes these macros in detail. 
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TASK GROUP CONTROL FUNCTIONS 


A task group iS a named set of one or more tasks, memory 
Space, files, peripheral devices, and priority levels. Any num- 


ber of task groups may be defined. The macro calls for task 
control allow you to: 


o Create a task group 

Oo Request a task group 

o Delete a task group 

O Spawn a task group 

o Suspend a task group 

Oo Activate a suspended task group 


o Terminate current task group and restart task group 
request 


o Abort a task group request 
o Abort a task group 


A task executing under one task group can initiate another 
task group. A task group must first be defined to create task 
group control structures and load the bound-unit root segment as 
the lead task. A group request must be issued to activate the 
lead task for execution. Tasks can be executed concurrently in 
this task group with the use of task control functions or 
commands. 


The task group can be deleted; no more requests can be made 
against this task group after it has been marked for deletion. 
When all tasks in the task group terminate and become dormant, 
all memory associated with the task group is returned to its 
memory pool, making that memory available to other task groups. 


The above effects of create, request, and delete a task group. 
occur in sequence when a spawn task group macro call is issued. 


A task can suspend a task group's execution and then acti- 
vate that task group. 


A task can terminate the current task group request and then 
restart the processing of the original task group request. 


A task can abort the current request for the activation of a 


specified task group. In this case the next request, if any, 
against that task group, will be processed. 
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To delete the task group immediately, before all its tasks 


terminate and become dormant, the group can be aborted. 


Some macro calls listed below use parameter blocks. 


The macro call to generate parameter blocks is discussed and 


described in Sections 4 and 5; block format is shown in Appendix 


A. 


TRAP 


kind 


The macro routines/calls for task group control are: 


Abort group SABGRP 
Abort group request SABGROQ 
Activate group SACTVG 
Create group SCRGRP 
Delete group SDLGRP 
New process SN PROC 
Request group SROQGRP 
Spawn group SS PGRP 
Suspend group SSUS PG 


Section 5 describes these macros in detail. 


HANDLING FUNCTIONS. 


The macro calls for trap functions allow you to indicate the 
of trap handling functions within the task group of the 


issuing task. The macro calls allow you to: 


o Connect a user-written, generalized trap handling routine 
to a task 


Oo Enable a specific trap or all traps 
o Disable a specific trap or all traps 
Section 7 describes traps and trap handling in detail. 


The macro routines/calls for trap handling are: 


Disable user trap SDSTRP 
Enable user trap SENTRP 
Trap handler connect STRPHD 


Section 5 describes these macros in detail. 
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SECTION 3 


FILE SYSTEM FUNCTIONS 


The macro routines summarized and listed in this section 
enable you to use the file system functions, which are organized 
according to the following major functional groups: (see column 
4 in Table 1-1): 


Oo File/directory management 
o Data management 
o Storage management 


The file/directory management macro routines provide service 
functions at the file level (i.e., creating files, reserving 
files, specifying concurrency control, opening and closing files, 
Creating directories, etc.). Data management macro routines Sup- 
ply the service functions required at the record level, such as 
read, write, delete, and rewrite. The storage management macro 
routines furnish service functions at the block (unit of trans- 
fer) level, such as read and write. 


Every macro routine/call is described in detail in Section 5 
in the alphabetic order of its function description (see column 2 
of Table 1-1). 


File management services use argument structures, which vary 
in content from macro call to macro call. The content of each 
argument structure is described with the appropriate macro call. 


"Addressing Conventions" in Section 1 describes the address 
forms that are valid for address and data registers. 


A pointer in the file system structures consists of two 


words. In SAF, the pointer resides in the first word; in LAF the 
pointer is a double-word address. 
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Some macros, particularly the data and storage management 
services, use a data structure called a file information block 
(FIB), which is generated with a SFIB macro call (see Sections 4 
and 5). The following are detailed descriptions of the structure 
and contents of the file information block (FIB). 


FILE INFORMATION BLOCK (FIB) 


There must be one file information block for each file, in 
order for the file to be accessed. The FIB, which must start on 
a word boundary, provides the interface between your program and 
the system for performing data- and storage-management functions. 
Table 3-1 describes each of the FIB entries, Table 3-2 describes 
the second entry in the FIB (i.e., program view) in detail. 


The FIB can be generated by a S$FIB macro call (see Sections 
4 and 5). 


Table 3-1. Contents of File Information Block (FIB) 


Size | 
Entry (bytes) Description 


Logical file Specifies the logical file number 

number (LFN) (LFN) by which the file is refer- 
enced. The LFN is the common ele- 
ment linking the FIB and the exter- 
nal file; this connection is made 
via the SASFIL, SCRFIL, or SGTFIL 
macro call (or equivalent command). 


Program view Describes the user visibility of the 
file and its functional capabili- 
ties; it contains information speci- 
fic. to each of the function groups 
(see Table 3-2) as follows: 


Bits 0-9 File/directory management 
Bits 10-14 Data management 
Bits 13-15 Storage management 


As described in Table 3-2, the set- 
ting of bit O determines whether 
bits 13 and 14 are data management 
specific or storage management 
specific. 
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Table 3-1 


Entry 


User record 
pointer (for 
data manage- 
ment functions) 


Buffer pointer 
(for storage 
management 
functions) 


In record length 
(for data manage- 
functions) 


Transfer-size 


(for storage 
management 


functions) 


Out record length 
(for data manage- 
ment functions) 
or 


(cont). 


Contents of File Information Block (FIB) 


Size 
(bytes) 


oN 


a oe ee the start of the user- 
record area as follows: 


SRDREC - Identifies the eeorege area 
into which records are delivered by 
the system. 


SRWREC, SWRREC - Identifies the 
Storage area from which records are 
taken by the system. 


The storage area must be large 
enough to contain the longest re- 
cord, excluding headers, to be 
written to or received from the 
file. 


Identifies the start of the buffer 
area as follows: 


SRDBLK —- Identifies the buffer area 
into which blocks of data are de- 
livered. 


SWRBLK -—- Identifies the buffer area 
oa which blocks of data are taken. 


Specifies the maximum size of the 
user-record area for SRDREC opera- 
tions. 


Specifies the size of the data 
transfer (i.e., the size of the buf- 
fer) for storage management 
operations. 


Specifies the actual size of the 
record to be written or read, as 
follows: 


SRDREC - The system updates this 
entry to reflect the actual length 
of the last record delivered into 
the user-record area. 
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Table 3-1 (cont). Contents of File Information Block (FIB) 


Size 
(bytes) Description 


SRWREC, SWRREC - Specifies the 
actual length of the record, exclud- 
ing the headers, to be written in 

the file. 


Block size 
(for storage 
management 
functions) 


Specifies the size of the block for 
storage management operations; for 
disk files the size must be a multi- 
ple of physical sector size. 


Reserved Must specify Z'OOOOFFFF'. 


Block number 


(for storage 
management 
function) 


Specifies the starting block number 
for the I/O transfers; is relative 
to the start of the file and to the 
block size (described above). This 
entry is incremented by 1 after each 
I/O transfer; therefore, user's 
dynamic changes to the block size 
also require changes to the contents 
of this entry. The first block in a 
file is block 0. 


In key pointer Identifies the start of the user-key 
area in which the key value is 
stored for the following SRDREC 
macro call functions: 


Read with key 


Read position equal 

Read position greater than 

Read position greater than or equal 
Read position forward 

Read position backward 
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( Table 3-1 (cont). Contents of File Information Block (FIB) 


Entry (bytes) 


In key pointer 
(cont.) 
[ 


In key format 


In key length 


7 


For the following SWRREC macro call 
functions: 


Write with key 

Write position equal 

Write position greater than 

Write position greater than or equal 
Write position forward 

Write position backward 


For the following SRWREC macro call 
function: 


Rewrite with key 


And for the following SDLREC macro 
call function: 


Delete with key 


The type of key is specified in the 
"in key format" entry below. 


Identifies the type of key pointed 
to by the "in key pointer" entry 
above, as follows: 


0 - None specified 


1 - Primary or relative, as speci- 
fied in the "key type" field in 
the "program view" entry; see 

Table 3- 


2 - Simple key 
The entry is meaningful only for the 


macro calls specified in the "in key 
pointer" entry defined above. 


Specifies the length of the user-key 
area identified in the "in key 
pointer" entry described above. 

Only meaningful for primary keys; 
simple and relative keys always 
assumed to be four bytes. 
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Table 3-1 (cont). Contents of File Information Block (FIB) 


Size 
Entry (bytes) Description 
Out record address 1 This field is available for the 
system to place the media address of 
the record dealt with by the last 
data management macro call. 


Normally, this address is a 32-bit 
simple key (i.e., it specifies the 
control interval and logical record 
within the control interval). 


However, if the file is accessed via 
a relative key as specified in the 
"in key format" field, then this 
address is a 32-bit relative key 
(i.e., relative logical record 
number in the file). If the opera- 
tion is not performed as specified, 
this entry is not set (and an error 
code is returned). 


For card readers, printers, and 
terminal devices, this field con- 
tains a count of the records 
transferred; i.e., this field is 
incremented by 1 for each logical 
sequential access to the device. 


use. 


Program View Entry in the FIB 


Table 3-2 shows the contents of the 2-byte FIB program view 
entry. The program view entry describes to the file system how 
the file is to be accessed and, to some extent, what it looks 
like from the programmer's point of view. The contents of this 
entry are used by the file system to ensure that the file is 
accessed only as intended. 


The bits in the program view entry are read at the time the 
file is opened. Once the file is opened, you can change only 
bits 11, 12, and 13. You cannot change the other bits until you 
close the file and then reopen it. 
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Table 3-2. Contents of Program View Entry in FIB 


Access level 
(Bit Q) 


Process rules 
(Bits 1-4) 


Specifies whether file is 
accessed via data or 
storage management macro 
calls as follows: 


O — Access via data man- 
agement macro calls. 


1 - Access via storage 
management macro 
calls. 


Specifies how the file can 
be processed; that is, it 
specifies which types of 
data/storage management 
macro calls are allowed as 
follows: 


Permitted Macro 


Binary Calls 


1000 SRDREC or SRDBLK 
0100 SWRREC or SWRBLK 
0010 SRWREC 
0001 SDLREC 


nnnn Any combination 
of the binary 
settings to allow 
the desired data/ 
storage management 
macro calls listed 
above. 


If a macro call that is 
not permitted (as speci- 
fied in this field) is 
issued, an access viola- 
tion error results. 


Related 
Function 
Group 


File Management 
(SOPFIL only) 
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Table 3-2. Contents of Program View Entry in FIB 


Related 
Function 


Specifies the type of File Management 
keys that can be used to (SOPFIL only) 
access the file as fol- | 
lows: 


Permitted Key 
Binary Type 


10000 Primary keys 
allowed 


00010 Relative keys 
allowed 


00001 Simple keys 
allowed 


n0Onn Any combina- 
tion of the 
binary settings 
to allow the 
desired keys to 
be used by the 
data management 
macro calls. 


If the key type specified 
in this field is not per- 
mitted by the type of file 
being processed, a bad 
program view error 
results. The following 
types of keys are allowed 
by the specified types of 
files: 


File File Management | 
Organization Key Type (SOPFIL only) 


| Fixed-rela- Relative 
tive Simple 


Relative Relative 
Simple 
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¢ Table 3-2 (cont). Contents of Program View Entry in FIB 


Related 


Function 
Description Group 


Sequential Simple File Management 
(Disk- (SOPFIL only) 
resident) 


Key type 
(cont). 


Indexed Primary 
Simple 


(Also see the "in key 
format" entry in Table 
3-1.) | 


Record class 
(Bit 10) 


Specifies type of logical Data Management 
records that can be pre- 

sent in the file as fol- 

lows: 


O - Any type (i.e., fixed- 
or variable-length 
records allowed). 


1 - Only fixed-length 
records allowed. 


Specifies whether or not 
deleted records are 
skipped during read next 
record (SRDREC) operations 
as follows: 


visibility 
(Bit 11) 


0 - Deleted records not 
visible (i.e., skip 
them). 


Deleted records are 
visible (i.e., the 
system issues the 
record not found 
return code when a 
deleted record is 
accessed). 
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Table 3-2 (cont). Contents of Program View Entry innFIB gre 


try Bits Related ee 
ie Descr Function 
sotctele | iption 


Key storage Specifies the boundary Data Management 
area align- alignment of the user- 
ment (Bit key area (see "in key 
12) | pointer" entry in Table 
3-1) as follows: 


Q —- Key storage area 
begins at even-byte 
boundary. 


1 - Key storage area 
begins at odd-byte 
boundary. 


Record Specifies the boundary Data Management 
storage alignment of the user- 
area/buffer record area (see “User 
alignment Record Pointer" entry 
(Bit 13) in Table 3-1) as fol- 
lows: 


0 —- Record storage 
area begins at 
even-byte boundary. 


Record storage 
area begins at 
odd-byte boundary. 


Same as above, except that }; Storage 
the boundary alignment Management 
refers to the buffer. 


Transcrip- Specifies how data is Data Management 
tion mode transferred as follows: 
(Bit 14) 


0 - Data is tranferred 
in device-specific 
native (ASCII) mode. 


Data is transferred 
in binary transcrip- 
tion mode. (See 
Note 2.) 
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Table 3-2 (cont) Contents of Program View Entry in FIB 


Related 
Size Function 
Entry (Bits) DeScription Group 


Ds 8 gale PG a nce BE i Re Dy te yg ap ae 
Same as above. 


Transcription 
mode (Bit 14 


Storage 


Management 
cont.) 


3 
synchronous/ 1 
asynchronous 
indicator 
(Bit 15) 


NOTES: 1. Bits 10 through 15 may be set after an SOPFIL macro 


call and before any data or storage management macro 
call. 


Specifies whether or not 
SRDBLK or SWRBLK macro 
calls are executed 
synchronously or asyn- 
Chronously as follows: 


Storage Manage- 
ment 


0 -— SRDBLK or SWRBLK macro 
calls are to be 
executed synchronously. 
When synchronous 
SRDBLK or SWRBLK macro 
calls are issued, a 

SWTBLK macro call is 

not required to 

synchronize buffer use. 


SRDBLK or SWRBLK macro 
calls are to be 
executed asynchron- 
ously (i.e., a SWTBLK 
macro call is required 
to synchronize.) 


Binary transcription mode is meaningful only for card 
devices and for 7-track magnetic tape. For card de- 
vices, this mode is equivalent to verbatim mode (See 
Section 6). For 7-track magnetic tape, binary trans- 
cription mode is usable only with storage management 
and is equivalent to packed mode (see Section 6). 


Offsets Definitions 


You can refer to specific locations in the file information 
block and the various argument structures by using offsets defin- 
ition macro calls. These calls, summarized in Section 4 and des- 
Cribed in detail in Section 5, define standard offsets tags. 
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Table 3-3 shows the offsets definition macro calls and the 
structures for which they define tags. 


Table 3-3. Offsets Definition Macro Calls 


Macro Call Affected Structure 
REESE TEE SATE OE CT INR ‘SUSIE Ra SDN NORTE AD Se REED RO Rag ae ET 
SCRPSB Argument structure for create file macro call 
(SCRFIL) 


SGTPSB Argument structure for get file macro call 
| (SGTFIL) 


SGIPSB Argument structure for get file information 
macro call (SGIFIL) 


SGIFAB File attribute block pointed to by $GIFIL 
argument structure 3 


SGIKBD Key descriptor block pointed to by the S$GIFIL 


and SCRFIL argument structures. 


STFIB File information block for the following 
: | macro calls: 


Open file (SOPFIL) 

Close file (SCLFIL) 

Test file (STIFIL, STOFIL) 
Read record (S$RDREC) 

Write record (SWRREC) 
Rewrite record (SRWREC) 
Delete record (SDLREC) 
Read block (S$RDBLK) 

Write block (SWRBLK) 

Wait block (SWTBLK) 


Offsets definition macro calls can be specified only once 
per assembly procedure. They provide tags that are equated to 
specific offsets in argument structures and FIBs. For example, 
assuming that the address of an argument structure labeled 
FILE A has been loaded into a base register as follows: 


LAB $B4,FILE_A 
and assuming that S$CRPSB has been specified, the following ad- 
dress syllable can be used to refer to the argument structure 


entry that identifies the control interval size: 


$B4.R_CISZ 
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This entry effectively points to the displacement FILE A+5 in the 
parameter structure. 


Section 5 describes each displacement definition macro 
routine/call and its tags, displacements, and entry names In 
detail. 


ASSUMPTIONS FOR FILE SYSTEM EXAMPLES 


The example shown for each file system macro call descrip- 
tion in Section 5 is based on the following assumptions. 


1. All the following displacement definition macros were 
specified: 


SCR PSB 
SGTPSB 
SGIPSB 
SGIFAB 
SGIKDB 
STFIB 


2. The following argument structures were defined: 


a. Argument structure for create file (SCRPSB) 


FILE A DC Z'0005' LFN 5 
~ De <IDXO1  PATHNAME PTR. 
RESV 2-SAF 
DC Z'4900' FILE ORG = I (INDEXED) 
DC 80 LOG. RCD. SZ. = 80 
DC 512 Cedl~. OZ. “= 522 
DC 5 INIT. ALLOC. SZ. = 5 
DC 10 MAX. ALLOC. SZ. = 10 
DC 320 FREE SPACE = 320 
DC 2 LOCAL OVERFLOW ALLOCATION INCREMENT=2 
DC 1 NO. OF KEY DESCR. = 1 
DC < KEY KEY DESCRIPTOR PTR. 
RESV 2-SAF 
RESV 4,0 RESERVED 
b. The pathname addressed by the previous structure 
(FILE A) 
IDXO1 DC '“VOLO3>SUBINDEX.A>FILE AA' 


c. File information block (SFIB) 
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MYFIB DC Z‘'OO0O5' LFN 5 


DC Z*2000' PROG. VIEW = ALLOW WRITE 

DC <INBUF USER RECORD PTR. 

RESV 2-SAF 

DC 256 MAX. INPUT RCD. SZ. = 256 
DC 256 - OUTPUT, RCD. SZ. = 256 

DC Z'OOOOFFFF' RESERVED 

DC Z*'0000'! RESERVED 

DC <MYKEY INPUT KEY PTR. 

RESV 2-SAF 

DC Z'O10A' INPUT KEY=PRIMARY; KEY LENGTH=10 
RESV 2,0 RECORD ADDRESS : 
RESV_.2,0 RESERVED 


When necessary, other structures are defined in the file 
system macro call examples. 


FILE MANAGEMENT FUNCTIONS 

The file/directory management macro calls allow you to mani- 
pulate your files within the file system hierarchy (described in 
the System Concepts manual). Specifically, the calls allow you 
to: 

o Create a file 

o Get a file (reserve a file for processing) 

o Open a file 

o Close a file 

Oo Release a file 

o Remove a file from processing 

o Rename a file 

o Associate a logical file number with a pathname 

o Dissociate a logical file number from a pathname 

o Create a directory 

o Release a aeckorD 

o Rename a directory 


o Change the working directory 


o Get the name of the current working directory 
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Expand pathname (develop a full pathname from a relative 


pathname) 


Get information about a file 


Test the status of an I/O activity (terminal) 


Wait for the completion of an asynchronous I/O activity 
(terminal) 


Set the file characteristics of a terminal. 


Some of the macro calls use file information blocks (FIBS); 


Some can use FIB offsetS or parameter Structure offsets. 


macro calls available to generate FIBs and offsets are summarized 


in Section 4 and described in detail in Section 5. 


The macro routines/calls for file management are: 


Associate file 

Change working directory 
Close file 
Create directory 
Create file 
Dissociate file 
Expand pathname 
Get file 
Get file information 
Get working directory 
Open file 
Release directory 


Release file 
Remove file 


Rename file/directory 
Set terminal file 
characteristics 

Test file for input 
Test file output 

Wait for file input 
Wait for file output 


Section 5 describes these macros in detail. 


SASFIL 
SCWDIR 
SCLFIL 
SCRDIR 
SCRFIL 
SDSFIL 
SXPATH 
SGTFIL 
SGIFIL 
SGWDIR 
SOPFIL 
SRLDIR 
SRLFIL 
SRMFIL 
SRNFIL 
SSTTY 


STIFIL 
STOFIL 
SWIFIL 
SWOFIL 


Many of the macro calls can be logically paired, as follows: 


0000 0 


Open file — Close file 
Create file - Release file 


Associate file - Dissociate file 


Get file 


Create directory - Release directory 


- Remove file 
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Although the following functions are available through macro 


calls, they are typically performed outside of program execution 
via execution control commands. 


Associate file 
Dissociate file 

Get file 

Remove file 

Create file 

Release file 

Rename file 

Create directory 

Change working directory 
Release directory 

Get working directory 
Set terminal file characteristics. 


OoO000 0O0 00000 0 


Figure 3-1 shows the life cycle of a file. Create file 
(SCRFIL) and get file (S$GTFIL) are actually on the same level. 
The same is true for release file (SRLFIL) and remove file 
(SRMFIL). (Associate file and dissociate file provide a way of 
supplying a pathname as input to create file and get file.) 


DATA MANAGEMENT FUNCTIONS 


The data management macro calls handle only logical records; 
to do your own blocking and deblocking, you must use the storage 
management macro calls (see following discussion). If you handle 
your files at the logical record level (as described in the Data 
File Organizations and Formats manual), the data management macro 
routines can be used to perform any of the necessary I/O opera- 


tions. Specifically, the data management macro calls allow you 
to: 


Write a record 
Rewrite a record 
Read a record 
Delete a record 


0000 


The definitions of arguments in the data management macro 
calls include identification of required file information block 
(FIB) entries, which are described at the beginning of this sec- 
tion. The macro calls to generate and change FIBs and to define 
FIB offsets are discussed in Section 4 and described in detail 
in Section 5. 


Note that before any data management macro calls can be 
executed, the file must have been reserved and opened with the 
LFN supplied in the FIB. See "Get File" and "Open File" in 
Section 5. 
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Figure 3-l. Life Cycle of a File 


3=17 


CBO8 


The macro routines/calls for data management functions are: 


Delete record SDLREC 


Read record SRDREC 
Rewrite record SRWREC 
Write record SWRREC 


Section 5 describes each macro in detail. 
STORAGE MANAGEMENT FUNCTIONS 


The storage management macro calls provide a primitive I/O 
interface for transferring blocks directly between your buffer 
and a file. Storage management itself is used by data management 
to perform input/output. 


The complexities of blocking and deblocking logical records, 
and conforming at the same time to the various file organizations 
and formats, recommend against using storage management when 
dealing with I/O at the logical record level. To ensure maximum 
efficiency in terms of space and access, let the system (i.e., 
data management) handle your records. 


However, with unblocked records or large blocks with simple 
fixed-length records that you want to block yourself, the storage 
management macro calls can be used to perform I/O transfers bet- 
ween your buffer and the file. In addition, the macros offer an 
asynchronous I/0 facility that lets you overlap I/0 transfers 
with task execution. Specifically, the storage management macro 
calls allow you to: 


o Read a block 
o Write a block 
o Wait for the completion of an I/O activity 


Block size for disk files must be some multiple of physical 
sector sizes. 


The definitions of arguments in the storage management macro 
calls include identification of required file information block 
(FIB) entries, which are described at the beginning of this sec- 
tion. The macro calls to generate FIBs and define FIB offsets 
are discussed in Section 4 and described in detail in Section 5. 


Note that before any storage management macro calls can be 
executed, the file must have been reserved and opened with the 
LFN supplied in the FIB. See "Get File" and "Open File" macro 
descriptions in Section 5. 
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The macro routineS/calls for storage management functions 
are: 

Read block SRDBLK 

Wait block SWTBLK 

Write block SWRBLK 


These macros are described in detail in Section 5. 
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SECTION 4 


DATA STRUCTURE GENERATION 


This section summarizes the macro routines that generate 
and/or define the system data structures. There are two kinds of 
data structure, those that apply to the monitor service func- 
tions, and those that apply to the file system functions. 


The macro calls for data Structure generation for both 
monitor services and for the file system functions, are described 
in detail in Section 5, in the alphabetic order of their function 
descriptions (see column 2 of Table 1-1). 


MONITOR SERVICES DATA STRUCTURES 
Monitor service data structures are the following: 


o Request blocks 
o Parameter block and wait 1ist 
oO Request block offsets 


The macro routines for generating the monitor services data 
Structures, Summarized in this subsection and described in 
Section 5, cannot be used in programs written in SAF/LAF inde- 
pendent code (SLIC). See the Program Preparation manual for 
detailed information about SAF/LAF independent code. 


Request Blocks 


Request blocks are data structures used by an application to 
coordinate the processing of events. The request blocks provide 
a Standard system interface that specifies the conditions for 
execution to proceed. For example, one element in a request 
block can be set to indicate that a task issuing a request for 
another task has the option to wait until the second task fin- 
ishes processing before the issuing task continues its own 
processing. 
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Request blocks provide the means of specifying the following 
options: 


Wait for requested task completion 
Explicit start address of requested task 
Termination action for requested task 
Deletion of request block upon termination 


000 0 


The wait option allows synchronization of a requesting and 
requested task; for example, the issuing task could name a sSema- 
Phore to be released or it could specify an address of a request 
block to be scheduled. 


The selection of an explicit start address allows a request- 
ing task to control the entry point of the requested task. 


Possible termination options of the requested task include 
release of a semaphore or request of another request block on 
task termination. These options allow flexible synchronization 
among tasks of an application and permit the issuing task to 
terminate before the requested task completes. For example, a 
Slave task that runs asynchronously with the remainder of the ap- 
plication can repetitively reserve a semaphore and be activated 
only by release of that semaphore as requested at termination of 
other tasks. The option of scheduling another task request at 
task termination allows, for example, a dispatching task to be 
notified of completion of certain tasks without explicitly wait- 
ing for their completion. 


The request block deletion option causes the system to re- 
turn the request block to the appropriate pool upon task termina- 
tion without further application intervention. 

Often used in conjunction with the semaphore and/or schedule 
request options, this is a way for memory to be properly returned 
even though the issuing task has itself terminated. For example, 
the system uses this feature on asynchronous task requests such 
aS Spawn Task, with the NWAIT argument. 

These options are controlled by the following specific bits 
in the request blocks, and apply to all types of requests 
(unless otherwise indicated). 

o W-bit, or wait 


o I-bit, or implicit start address (not optional for IORBs, 
always set) 


o S-bit, or semaphore 
o R-bit, or return request 
o D-bit, or delete 
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The assignment of these control bits within the request blocks is 
shown in Appendix A. 


Request blocks also carry parameters from the issuing task 
to the requested task or to the system service. A variable- 
length area is available in the task request block for intertask 
communication of application-specific parameters. 


The specific request blocks generated by the macro calls 
listed below are: 


Task request block (TRB) 

Input/foutput request block (IORB) 

Message group request blocks (MGCRB, MGIRB, MGRRB) 
Semaphore request block (SRB) 

Clock request block (CRB) 


00000 


A field in a request block that is not set by its corres- 
ponding argument in the request block macro call is set to zero 
when the block is generated. You may change these zero fields to 
any desired value. | 


The first four words of the request blocks are identical in 
format (see Appendix A. for a diagram of each structure). Addi- 
tional words carry parameter information specific to the request 
block type. 


There is van offsets macro call for each form of request 
block. These macro calls, described in Section 5, create expli- 
cit labels for request blocks. 


The macro routines/calls to generate the request blocks are: 


Clock request block SCRB | 

Input/foutput request block SIORB 

Message group request blocks (SMGCRB, SMGIRB, SMGRRB) 
Semaphore request block SSRB 

Task request block STRB 


Section 5 describes these macros in detail. 


Parameter Block and Wait List 


The macro routines listed below generate data structures 
with a format different from that of the request blocks described 
above. These data structures are: 


Oo Parameter block 
o Wait list 


Their formats are shown in Appendix A. 
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The macro routines/calls for generating a paramenter block 
and a wait list are: 


Parameter block, generate SPRBLK 
Wait list, generate SWLIST 


Section 5 describes these macros in detail. 
Request Block Offsets 


The request block offsets macro routines generate data 
structure definitions for request blocks that will be constructed 
at a later time by application code. The request block defini- 
tions supplied by the offsets macro calls have explicit labels 
for each entry in the structure, allowing symbolic displacement 
references to be made in application code. 


NOTE: The request block macro calls previously 
described generate actual request blocks; the 
displacement entry labels are not included. 
The contents of the request block fields are 
set according to the arguments supplied in 
the macro calls. 


No arguments are specified with the offsets macro calls. 
Only one request block offsets macro of a particular type is re- 
quired in an assembly program referencing its entries. 


You may include several different templates containing the 
four common request block fields in your code because the tem- 
plate for each structure begins with a unique identification 
Character prefix. This technique avoids assembly error notices 
of multiple defined symbols, when, for example, the control word 
l entry label of a TRB and IORB are both included in the applica- 
tion source program. 


Note that a program may use a request block macro routine to 
initially define a desired block, and also include that same type 
request block offsets to facilitate modification of the initial 
block by executing code. 


The request blocks offsets generated by the offsets macro 
calls are: 


Generated by 


o Task request block (TRB) offsets STRBD 


Oo Input/output request block (IORB) offsets SIORBD 
o Clock request block (CRB) offsets SCRBD 
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Generated by 
macro call: 


o Semaphore request block (SRB) offsets SSRBD 
o Message group request blocks (MGCRB, SMGCRT 
MGIRB, MGRRB) offsets SMGIRT 
SMGRRT 


Section 5 describes each macro in detail. 
FILE SYSTEM DATA STRUCTURES 
File system data structures are the following: 


Oo File information block (FIB) 
o Offsets definitions 


File Information Block (FIB) 


The FIB is the principal means of communication between the 
application and the File System. 


Table 3-1 and Appendix A show the format and content of the 
file information block. The macro routine/call to build a file 
information block, or alter its contents, or provide labels for 
its entries, is: 

File information block SFIB 


Section 5 describes this macro in detail. 


Offsets Definitions 


With offsets definition macro calls, you can refer to 
specific locations in the file information block and in the 
various argument structures used by certain file system macro 
calls. 


The offsets definition macro calls, which can be specified 


only once per assembly procedure, provide tags that are 


equated to specific offsets in the argument structures and in the 
FIBs. 


Macro calls are provided to define tags for the following 
structures: 


o Create file (SCRFIL) macro call argument structure 
o Get file (SGTFIL) macro call argument structure 


o Get file information (SGIFIL) argument structure 
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o File attribute block pointed to by SGIFIL argument 
structure | 


o Key descriptor block pointed to by SGIFIL argument 
structure 


o File information block 


Only the macro call name is specified; these macro calls 
have no arguments. 


The macro routines/calls for offsets definition are: 


Create file parameter block SCRPSB 
Structure offsets 


File information block STFIB 
offsets 


Get file information SGIFAB 
file attribute block 
offsets 


Get file information SGIKDB 
key descriptor block 

offsets 

Get file information SGIPSB 
parameter structure block 

offsets 


Get file parameter structure SGTPSB 
block offsets 


These macros are described in detail in Section 5. 


Sue ae 


4-6 . CBO0O8 


SECTION 5 


MACRO ROUTINE/CALL DESCRIPTIONS: 


This section describes in detail the use, structure, func- 
tions, and return status error conditions for all system services 
macros referred to and listed in Sections 2, 3, and 4, and pro- 
vides an example for most macros. For easy reference, the 
descriptions are in alphabetic order by specific function name 
(see column 2 in Table 1-1). 


Each description includes a reference to the command (if 
there is one) that performs the equivalent function (see the 
Commands manual). AlSo included for each description is a repre- 
sentative list of possible return status (error) codes and the 
corresponding error condition for each return status. (See the 
System Messages manual for a complete list of GCOS 6 return 
Status codes and corresponding system messages.) 
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ABORT GROUP (MOD 400 ONLY) 
Macro Call Name: SABGRP 


Function Code: OD/0A 


Equivalent Command: Abort Group (ABORT _GROUP) 


Terminate the indicated task group and delete it. 


FORMAT: 


[label] SABGRP flocation of abort status], 
[location of group identifier] 


ARGUMENT DESCRIPTION: 


location of abort status 


Any address form valid for a data register; provides a 
completion status code that will be posted when the 
task group is terminated. The abort status code is 


used as the termination code of the lead task of the 
aborted group. 


location of group identifier 


Any address form valid for a data register; provides 
the group identification of the task group to be 
aborted. If this argument is omitted, the task group 
issuing the macro call is aborted. If a group identi- 
fier is specified, it must be the Same as that used in 


the create group macro call that initialized this task 
group. 
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FUNCTION DESCRIPTION: 


This call terminates an existing task group, whether the 
group is active or dormant. The abort group macro call 
removes all data structures that define and control execu- 
tion of the task group, and returns all memory used by the 
group to the appropriate memory pool. Any files that were 
open during execution of the task group are closed. Any 


requests pending against the group are canceled. The group 
is deleted. 


NOTES: 1. The abort status code supplied by argument 1 is 
placed in SR6; if this argument is omitted SR6 


is assumed to contain the abort status code to 
be used. 


2. The group identification suppled by argument 2 
is placed in $R2; if the argument is omitted, 
SR2 is set to zero to designate that the issuing 
task group is to be aborted. 


3. If a task group other than the issuing task 
group was aborted, S$R1 and $R2 contain the fol- 
lowing information upon return to the issuing 
task. 


SR1 - Return status; one of the following: 


COO00O0 - Abort task group status set 
0806 - Task group not found 


SR2 - Group id of aborted task group 


Example: 


In this example, the SABGRP macro call causes the processing 
of the current group request to be aborted with a completion 
Status of 40 (decimal). The task group is then deleted with 
any requests that may be queued on the group being 
discarded. 


SABGRP =40 
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ABORT GROUP REQUEST 


ABORT GROUP REQUEST 

Macro Call Name: SABGRQ 

Function Code: 0D/07 

Equivalent Command: Abort Group Request (AGR) 


Terminate the execution of the current request in the indi- 
cated task group. 


FORMAT: 


[label] SABGRQ [location of abort status], 
[location of group identifier] 


ARGUMENT DESCRIPTION: 
location of abort status 


Any address form valid for a data register; provides a 
completion status code that will be posted when the 
request is marked as terminated. The abort status 
code is used as the termination code of the lead task 
of the aborted group. 


location of group identifier 


Any address form valid for a data register; provides 
the group identification of the task group whose cur- 
rent request is to be terminated. If this argument is 
omitted, the current request of the issuing task group 
is terminated. If a group identifier is specified, it 
must be the same as that usSed in the create group or 
Spawn group macro call that initialized this task 
group. | 
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FUNCTION DESCRIPTION: 


This call causes the cessation of execution of the current 
request in the indicated task group. It removes all defin- 
ing and controlling data structures except those associated 
with the lead task (as defined by the create group macro 
call that specified this group id) and returns the associ- 
ated memory to the appropriate memory pool. 


Files that are open and in use by this task group are 
Closed. The abort process will not complete until all out- 
Standing input/output orders are completed. 


When the macro call has been executed, the abort status code 
is posted, the request is removed, and the lead task pro- 
cesses the next request for this group, if any. 


An abort group request for a spawned group is equivalent to 
an abort group monitor call. 


NOTES: 1. The abort status code specified by argument 1 is 
placed in S$R6; if this argument is omitted, SR6 
is assumed to contain the abort status code to 
be used. 


2. The group identification specified by argument 2 
is placed in SR2; if this argument is omitted, 
SR2 is set to zero to designate that the issuing 
task group request is to be aborted. 


3. If the current request of a task group other 
than the issuing task group was aborted, SR1 and 
SR2 contain the following information upon 
return to the isSuing task. 


SR1 - Return status; one of the following: 


0000 - Abort task group request status Set 
0806 - Task group not found 


SR2 - Group id of task group whose current 
request was aborted 


Example: oe 

In this example, the SABGRQ macro call causes the processing 
of the current group request to be aborted with a completion 
Status of 20 (hexadecimal). If additional requests are 
queued on the task group, the next (first) request in the 
queue will be processed. 


END 2 SABGRQ =X'20! 
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ACCOUNT IDENTIFICATION 


ACCOUNT IDENTIFICATION 
Macro Call Name: SACTID 
Function Code: 14/02 
Equivalent Command: None 


Returns the account component of the calling task group's 
user identification to a 12-character receiving field. 


FORMAT: 


[label] SACTID [location of account id field address] 
ARGUMENT DESCRIPTION: 
location of account id field address 


Any address form valid for an address register; pro- 
vides the address of a 12-character, aligned, non- 
varying field into which the system will place the 
account component of the user identification associ- 
ated with the issuing task group. 


FUNCTION DESCRIPTION: 


This call returns the account component (i.e., the account 
under which the user is working) of the task group's user 
identification to a field in the issuing task. See the 
Operator's Guide for more details. 


The entire user id is returned by the user identification 
(SUSRID) macro call. 


NOTES: 1. The address of the receiving account id field, 
supplied by argument 1, is placed in $B4; if 
this argument is omitted, S$B4 is assumed to con- 
tain the address of the receiving field. 
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2. On return, SR1 contains one of the following 
status codes: 


0000 - No error 
0817 - Memory access violation 


Example: 


In the following example, $B4 is loaded with the address 
(ACIDFL) of a 12-character field and the SACTID macro call 


is issued to place the account identification of the task 
group in that field. 


ACIDFL RESV 12,0 
LAB $B 4,ACIDFL 
SACTID 
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ACTIVATE GROUP 


ACTIVATE GROUP 

Macro Call Name: SACTVG 

Function Code: 0D/09 

Equivalent Command: Activate Group (ACTG) 
Reactivate a previously Suspended task group. 


FORMAT: 


[label] SACTVG flocation of group id] 
ARGUMENT DESCRIPTION: 
location of group id 


Any address form valid for a data register; provides 
the group id of the task group to be reactivated. 


FUNCTION DESCRIPTION: 


This call causes the system to reactivate the specified 
suspended task group. This task group must have been 
previously suspended through a suspend group macro call. 

The system requeues on the appropriate level queue all tasks 
that were active when the task group was suspended. 


If the group id argument is SB, the previously rolled out 
batch task group is rolled in when all online task groups 
have returned memory to the batch pool. Any task group that 
has explicitly rolled out the batch task group (through a 
SSUSPG $B macro call) should roll in the batch task group 
before terminating. If the task group does not issue a 
SACTVG $B macro call before terminating, or if the task 
group is aborted, the operator must issue an ACTB command to 
allow batch roll in. 
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( | Before it terminates, any online task group that has sus- 
— pended another online task group (through a $SUSPG macro 
call) should reactivate that task group. If the suspending 
task group does not issue a SACTVG macro call, or if the 
Suspended task group is aborted, the operator must issue an 
ACTG command for the suspended task group to resume. 


NOTES: 1. The group id of the task group to be reacti- 
vated, supplied by argument 1, is placed in SR2; 
if this argument is omitted, $R2 is assumed to 
contain the correct group id. 


2. On return, S$R1l and SR2 contain the following 
information: 


SR1 - Return status; one of the following: 
OO000 - No error 


0806 -—- Specified task group not currently 
defined | 


O80D ~- Specified task group not currently 
suspended 


SR2 - Group id as supplied 


MBAR: 


Example: 


In this example, the SACTVG macro call is used to reactivate 
the previously suspended task group whose group id is Gl. 
All tasks in task group Gl that were active when the group 
was suspended will be requeued on the appropriate level 
queue. 


ACTGAA SACT VG =G 1 
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ASSOCIATE FILE 

Macro Call Name: SASFIL 

Function Code: 10/10 

Equivalent Command: Associate Path (ASSOC) 


Associate a logical file number (LFN) with a specific path- 
name. This association is typically done outside of program 
execution to allow the program to be run against a pathname 
that is not known until execution time. The SGTFIL macro 
call or GET command may be more useful. 


FORMAT : 


[label] SASFIL fargument structure address] 


ARGUMENT DESCRIPTION: 


argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


logical file number 


A 2-byte logical file number (LFN) used to refer 
to the file; must be a binary number in the 
range 0 through 255. 


pathname pointer 


A 4-byte address, which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII space charac- 
ter) to be associated with the LFN. 
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FUNCTION DESCRIPTION: 


This macro call establishes a logical connection between an 
LFN and a pathname. It does not reserve a file or check to 
determine whether or not the pathname identifies an existing 
file or directory (i.e., the pathname entry may identify an 
incomplete pathname, such as VOL1 SUBA ). If you associate 
an incomplete pathname with the LFN, it can be completed at 
a later time by a get file macro call using the colon (:) 
option. Subsequent macro calls (e.g., change working 
directory) have no effect on a previously associated path- 
name because the pathname identified in this macro call is 
fully expanded at the time of the call. Finally, although a 
Single pathname can be associated with several LFNs, a given 
LFN can be asSociated with only one pathname at any given 
time; after a file reservation (see get file) has been 
established using a specific LFN, subsequent associations of 
the same LFN will alter the LFN/pathname relationships but 
will not affect current file reservation. It should be 
noted that the association established is specific to a task 
group; that is, different task groups can associate dif- 
ferent pathnames to the same LFN. 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into SB4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the argument structure. 


2. On return, SR1 contains one of the following 
Status codes: 


O0O00 - No error 

0201 - Illegal pathname 

0205 - Illegal argument 

0206 -—- Unknown or illegal LFN 
0210 - LFN already associated 


0222 - Pathname cannot be expanded, no working 
directory 


0226 —- Not enough user memory for buffers or 
structures 


In addition to the above, any system service 


codes received by the file manager are passed on 
through SRl. 
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Example: 


This example assumes that $B4 was loaded with the address of 
the label FILE A (i.e., LAB SB4,FILE A); therefore, the 
macro call to associate the path identified in the create 
file example (i.e., VOL03 SUBINDEX.A FILE A) with LFN 5 is 
coded as follows: 


ON LAA SASFIL 
FILE A was previously defined in "Assumptions for File 
system Examples" in Section 3; aS a result of isSuing the 


SASFIL macro call, the first two entries in that structure 
are referred to by the system. 
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BOUND UNIT IDENTIFICATION 
Macro Call Name: SBUID 
Function Code: 14/06 
Equivalent Command: USER BUID 


Returns the file name of the bound unit being executed by 
the issuing task to a 12-character receiving field. 


FORMAT : 


[label] SBUID [location of bound unit id field address] 


ARGUMENT DESCRIPTION: 


location of bound unit id field address 


aim, 


Any address form valid for an address register; pro- 
vides the address of a 1]2-character aligned, nonvary- 


ing receiving field into which the system will place 
the name of the current bound unit. 


FUNCTION DESCRIPTION: 


This macro call returns the name of the currently executing 
bound unit to a specified field in the issuing task. The 
name returned is that specified in the Linker NAME 
Statement. 


NOTES: 1. The address of the receiving bound unit id field 
supplied by argument 1 is placed in S$B4; if this 
argument is omitted, S$B4 is assumed to contain 
the address of the receiving field. 


2. On return, SR1 contains one of the following 
Status codes: 


0000 -— No error 
O817 -—- Memory access violation 


( 3. On return, S$B4 contains the address of the 
— | receiving field. 
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Example: 


In this example, SB4 is loaded with the address (BUNAME) of 
a 6-character field and the SBUID macro call is issued to 


place the name of the currently executing bound unit in that 
field. 


BUNAME RESV 6,0 | 
LAB $B4, BUNAME 


SBUID 
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CANCEL CLOCK REQUEST 


CANCEL CLOCK REQUEST 
Macro Call Name: SCNCRQ 
Function Code: 05/01 
Equivalent Command: None 
Cancel a previously issued clock request. 
FORMAT : 
[label] SCNCRQ [location of CRB address] 
ARGUMENT DESCRIPTION: 
location of CRB address 
Any address form valid for an address register; pro- 
vides the address of the clock request block (CRB) to 
be removed from the timer queue. 
FUNCTION DESCRIPTION: 
This call removes a no longer needed but previously queued 
CRB from the timer queue. The CRB must have previously been 
Placed on the queue by a request clock (S$RQCL) macro call. 
The SCNCRQ macro call is the only way to remove a cyclic 
CRB from the timer queue. A noncyclic CRB will also be 
removed when its interval elapses. 
NOTES: 1. The address of the CRB to be disconnected from 
the queue, supplied by argument 1, is placed 
SB4; if this argument is omitted, $B4 is assumed 


to contain the correct address. 


2. On return, S$R1 and S$B4 contain the following 
information: 
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SR1 - Return status; one of the following: 
O000 - No error 


0404 - CRB not connected to basic timer 
queue | 


SB4 - Address of CRB 
Example: 


see the example given for the wait on request list macro 
call in this section. 
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CANCEL REQUEST 


Macro Call Name: SCANRQ 
Function Code: 0O0OC/0Ol 
Equivalent Command: None 


Cancel a previously issued request made through a SROTML or 
STRB macro call. 


FORMAT: 

[label] SCANRQ [location of address of request block] 

ARGUMENT DESCRIPTION: 

location of address of request block 

Any address form valid for a data register; provides 
the address of the request block whose request is to 
be canceled. 

FUNCTION DESCRIPTION: 

This call cancels a previously issued request. The call is 

used to cancel a request established by a request terminal 

(SROTML) or task request block (STRB) macro call. 

NOTES: 1. The address of the request block containing the 
request to be canceled, supplied by argument 1, 
is placed in $B4. If this argument is omitted, 
the system assumes that SB4 contains the address 


of the request block. 


2. On return, SR1 contains one of the following 
Status codes: 


O000 - Terminal request canceled 


0803 - Illegal request block address (request 
block not found) 
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0817 - Memory access violation 
083C - Terminal request already posted 
3. When SR1 contains an 083C return code, SR6 con- 


tains the posted return code. The request block 
was completed before this macro call was issued. 


Example: 
In this example, the SCANRQ macro call is used to cancel the 
request established by a request terminal (SROTML) macro 


call. (See the example for the request terminal macro 
call.) 


END RQ SCANRO !ITORB 


o=L8 CBO0®& 


qrvenge 


CANCEL SEMAPHORE REQUEST 


CANCEL SEMAPHORE REQUEST 
Macro Call Name: SCNSRQ 
Function Code: 06/01 

Equivalent Command:. None 


If a previously issued request semaphore macro call caused a 
semaphore request block (SRB) to be queued, cancel the 
effect of that macro call by removing the SRB from the sema- 
phore request queue. Return to the issuing task. 


FORMAT : 

[label] SCNSRQ [location of SRB address] 
ARGUMENT DESCRIPTION: 
location of SRB address 


Any address form valid for an address register; pro- 
vides the address of the semaphore request block to be 
removed from the semaphore request queue. 


FUNCTION DESCRIPTION: 


This call removes a specified SRB from its semaphore request 
queue. The SRB must have been queued as the result of a 
previously issued request semaphore macro call. The SRB 
address specified in argument 1 of the cancel semaphore 
request call must be the same SRB address used in the 
request semaphore call. 


When executed, this function increments the counter estab- 
lished by the define semaphore macro call, and previously 
decremented by the request semaphore macro call. 


When the SRB iS removed from the semaphore request queue, 


the memory required for its structure is returned to the 
system memory area. 
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Example: 


The address of the SRB Supplied by argument 1 is 
placed in $B4; if this argument is omitted, $B4 
is assumed to contain the SRB address. 


On return, SR1 and SB4 contain the following 
information: 


SR1 - Return status; one of the following: 


Q000 -—- No error 
0502 - Invalid SRB 


SB4 - Address of SRB (as supplied) 


In this example, the SCNSRQ macro call is used to cancel the 
semaphore request used in the example for the request sema- 
phore macro call. It is assumed that the task did not need 
the resource. 


SCNSROQ !SRB 
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CHANGE WORKING DIRECTORY 

Macro Call Name: SCWDIR 

Function Code: 10/B0 

Equivalent Command: Change Working Directory (CWD) 


Change the working directory to the one specified in the 
macro call. This function is usually done outside program 
execution. 


FORMAT: 


[label] SCWDIR [argument structure address] 
ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entry. 


new working directory 


A l- to 45-byte pathname, which includes and 
must end with an ASCII space character, identi- 
fying the new current working directory. At 
least one nonspace character must be specified. 


FUNCTION DESCRIPTION: 


The specified pathname, which may be absolute or relative, 
must point to an existing directory; that is, this macro 
Call does not dynamically create a directory. If a return 
Status code other than 0000 is returned (see Note 2, below), 
an attempt is made to reestablish the previous working 
Girectory; if a subsequent error results, future functions 
may return an 0222 error code. 
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The system issues a mount request when a disk volume con- 
taining the new working directory is not mounted. The task 


is suspended until 


the volume is mounted or the operator 


cancels the mount request. 


NOTES: 1. If the 


argument is coded, the address of the 


argument structure is loaded into $B4; if the 
argument is omitted, S$B4 is assumed to contain 
the address of the parameter structure. 


2. On return, $R1 contains one of the following 


status 
0000 - 
0201 - 
0205 - 
0209 - 
Q020C - 


0222 - 


0225 = 


0226 - 


0225 = 


codes: 

No error 

Tllegal pathname 

Illegal argument 

Named directory not found 
Volume not found 


Pathname cannot be expanded, no working 
directory 


Not enough system memory for buffers or 
structures 


Not enough user memory for buffers or 
structures 


Illegal file type (not a directory) 


In addition to the above, any system service 
codes received by the file manager are passed on 
through SRl. 


Example: 


This example is based on the following file system hierarchy 
(see the System Concepts manual): 
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VOLO1 
SUB.DIR.A SUB.DIR.B 
SUB.DIR.AA | SUB.DIR.BB 
FTLEO! FILEO2 SUB.DIR.BB1 FILEO3 
FILEO4 SUB.DIR.BIB 


-—_1—__, 
FILEOS FILEO6 


The current working directory is SUB.DIR.B1B and you want to 
access FILEO1 from subdirectory SUB.DIR.AA. You need not 
specify the absolute pathname to FILEO1 if you specify the 
macro call SCWDIR to SUB.DIR.AA as shown below. The file 
can then be accessed with the simple pathname FILEO1. 


To change to this working directory, you can use the SCWDIR 
macro call: 


SCWDIR ! CHG PTH 


to identify the path: 


CHGPTH DC '<<<<SUB.DIR.A>SUB.DIR.AAA! 
or 
CHGPTH DC '“VOLO1>SUB.DIR.A>SUB.DIR.AAA' 


The first case uses the existing working directory as a base 
from which to expand the relative pathname; the second case 
produces the same result, but uses the absolute pathname; 
see the System Concepts manual for more information about 
relative and absolute pathnames. 
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CLEAN POINT 

Macro Call Name: SCLPNT 
Function Code: 0C/13 
Equivalent Command: None 


Defines a clean and consistent point in program execution at 
which all file records updated by the program are valid. 
These updated records are made visible to other users shar- 
ing these files. Writes out to disk the records updated by 
the issuing task group; unlocks the records previously 
locked by the issuing task group, for all files assigned to 


the task group. 
FORMAT :. 


[label] SCLPNT 
ARGUMENT DESCRIPTION: 
None | 
FUNCTION DESCRIPTION: 
This macro call results in the following: 


1. The buffers of updated records of files accessed by the 
task group are written to disk. 


2. If the end of data record for a disk file accessed by 
the task group is altered, the directory record for that 
file is updated. 


3. All record locks set by this task group are unlocked, 
thus allowing other users to continue. processing. 


Record locking, a file system mechanism, provides multi-user 
interface protection for shared file access. A record, when 
accessed by a user, is locked by a lock applied to the con- 
trol interval(s) where the record is located. Locking is on | 
a first-come first-served basis. Another user (task group) a. 


~. 
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Sharing this file is denied access to that record and any 
other record in the same control interval, until the pre- 
vious user unlocks the record. 


The only limit to the number of locks at one time is the 
amount of memory dedicated to the lock pool at system 
building. (The lock pool is that memory area where locked 
records are recorded.) 


Record locks for a file must be specifically requested when 
the file is reserved through a get file (SGTFIL) macro call 
or by a GET command. Once record locking for a file is 
requested, any access (read or write) causes a lock. Once 
locked, records are unlocked only when a clean point 
(SCLPNT) macro call is issued or the file is closed. 
(Abnormal task group termination also causes records to be 
unlocked.) 


Records should be unlocked when there is no further need to 
lock them. Otherwise, when records remain locked, lock pool 
overflow or deadlock record contention may result. The 
description of the get file (SGTFIL) macro call later in 
this section has more details about record locking. 


Clean point allows a user to structure an application into 
Steps. At the end of each step, Successful execution of the 
macro call ensures that all the file updates were written to 
disk, and that the resources used in record locking are 
released to the system. 


NOTES: 1. To perform the clean point function in a COBOL 
program, the user must call an assembly language 
subroutine that contains the SCLPNT macro 
call(s). 


2. On return, S$R1 contains one of the following 
Status codes: 


OCOO - No error 


0225 - Insufficient system memory for buffer or 
structures 

0226 - Insufficient user memory for buffer or 
structures - 


3. Any system service error codes received by data 
management are passed on through SRI. 
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CLEAR EXTERNAL SWITCHES. 

Macro Call Name: SCLRSW 

Function Code: 0B/02 

Equivalent Command: Modify External Switches (MSW) 


set the specified switches in the task group's external 


Switch word to off; return the inclusive logical OR of the 
Previous settings. 


FORMAT : 


[label] SCLRSW external switch name, 
7 [external switch name], 


fexternal switch name] 


ARGUMENT DESCRIPTION: 
external switch name ... external switch name 


A single hexadecimal digit specifying the external 
Switch in the task group's external switch word to be 
set off. A maximum of 16 external switch names (0 
through F) can be specified. If no arguments are 
supplied, SR2 is assumed to contain a mask word spec-— 
ifying the switches to be set off. If ALL is spec- 


ified for any argument, all external Switches are set 
off. 


FUNCTION DESCRIPTION: 
This call provides a mask by which switches can be set off 
in the external switch word of the issuing task's task 


group. It also provides an indication of the previous set- 
tings of the switches. 
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SR2 is the mask word. Each bit that is 1 in $R2 causes the 
corresponding bit in the external switch word to be set off; 
each bit that is 0 causes the corresponding bit to remain 
unchanged. | 


When the SCLRSW macro call is executed, S$R2 contains the new 
settings of the external switch word. Bit 11 (bit-test 
indicator) or the I-register provides an indication of the 
previous setting of the switches, as follows: 


o If bit 11 is 0, no switch set off had previously been set 
on. 


o If bit 11 is 1, at least one switch set off had pre- 
viously been set on. 


NOTES: 1. The bits corresponding to the external switches 
in the arguments are set on in SR2; if no argu- 
ments are supplied, SR2 is assumed to contain 
the mask to be used. If ALL is specified for 
any argument, all bits are set on in SR2. 


2. On return, SR2 and the I-register contain the 
following information: 


SR2 - External switch word after modification 


I-register (Bit 11) - Inclusive OR of previous 
settings of switches set off: 


0 -— No switch set off was on 
1 - At least one switch set off was on 


Example: 
In this example, the SCLRSW mcaro call is used to turn off 
external switches 4, 8, and C of the task group in which the 


issuing task is executing. 


CLR AA SCLRSW 4,8,C 
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CLOCK REQUEST BLOCK 

Macro Call Name: SCRB 
Function Code: None 
Equivalent Command: None 


Generate a regular or cyclic clock request block (CRB) whose 
length is from six to nine words. 


FORMAT: 


[label] $CRB [CRB type], 
[issuing task susSpenSion option], 


or 


ftrermination action], 
finterval value] 


ARGUMENT DESCRIPTION: 


CRB type 


A value specifying the type of CRB to be generated, as 
follows: 


C - Generate a cyclic CRB 
R - Generate a regular (noncyclic) CRB 


issuing task suspension option 
One of the following values is specified to indicate 
whether the requesting task is to be suspended until. 


the clock request has been satisfied. 


WAIT - Suspend the issuing task until the clock 
request has been satisfied (set w-bit to 0). 


NWAIT - Do not suspend the issuing task (set w-bit 
to l). 
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If this argument is omitted, the value NWAIT is 
assumed. 


If WAIT is specified, argument 3 (termination action) 
must be omitted. 


termination action 


One of the following values is Specified to indicate 
the action to be taken when the clock request is 
satisified. 


SM=aa - Do not suspend the isSuing task; release 
(V-op) the semaphore identified by aa (two 
ASCII characters) when timeout has 
occurred. 


RB=label - Do not Suspend the issuing task; issue a 
request for the request block identified by 
label, when timeout has occurred. 


If this argument is omitted (or argument 2 is WAIT), 
the generated CRB contains no termination option. 


interval value 


Unit of time after which completion of the request 
will be posted; has one of the following values: 


MS=n 
TS=M. 
SC=m 
MN=m 
CT=m 


MS indicates milliseconds; TS tenths of seconds; SC 
seconds; MN minutes; and CT units of clock resolution. 


n is an integer value from 1 through 65535; m is an 
integer value from 1 through 32767. 


If this argument is omitted, the CRB is initialized 
with an interval value of zero milliseconds (MS=0). 


FUNCTION DESCRIPTION: 


The clock request block (CRB) is used as the standard means 
of synchronizing events with the passage of time. A CRB 
contains the time at which, or the interval after which, 
completion of the request is to be posted (marked as 
complete). | 


There are two types of CRBS; regular and cyclic. 
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When the interval specified in a cyclic CRB has been satis- 
fied, it is automatically recycled to begin a new clock 
request for the initially specified interval. This process 
continues until a cancel clock request macro call is issued 
for this CRB. 


A regular CRB is dequeued from the timer queue when the 
specified interval has been satisfied. A new request clock 
macro call must be issued to requeue the CRB. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 
independent code. 


Example: 


In this example, the SCRB macro call is used to generate a 
cyclic CRB with an interval of 500 milliseconds. The issu- 
ing task is not to be suspended. When the request has been 
satisfied, the issuing task will release semaphore XxX. 


CLKAA SCRB  C,NWAIT,SM=XX,MS=500 
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CLOCK REQUEST BLOCK OFFSETS (MOD 400 ONLY) 
Macro Call Name: S$CRBD 
Generated Label Prefixes: 
C_RRB/C_SEM 
CRB label offset 0 
c cTl 
C CT2 
Cc T™ 
See Appendix A for the format of the clock request block. 
DESCRIPTION: 
see the clock request block macro call. 
NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 


Preparation manual for more information 
about SAF/LAF independent code. 
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CLOSE FILE 


CLOSE FILE 

Macro Call Name: S$CLFIL 

Function Code: 10/55 (normal), 10/56 (leave), 10/57 (unload) 
Equivalent Command: None | 


Terminates processing of the specified file. The file can- 
not be processed again until another open file macro call is 


issued. You identify the file to be closed by supplying its © 


logical file number. | 
FORMAT: 
‘eave | 


[label] SCLFIL [fib address] | \(, LEAVE 
| , UNLOAD 


ARGUMENT DESCRIPTION: 
fib address 


Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). The FIB must contain a valid LFN. 


= 
NOR 


Normal mode for closing files; the file can be. 
reopened during execution of the task group. 


If the file is tape-resident, the end-of-file (EOF) 
labels are written (if necessary) and the tape is 
rewound to its beginning-of-tape (BOT) position. 


If the file is a terminal device, the line will be 
disconnected according to the specifications made at 
system building time. 


NORMAL is the default value for this macro call. © 
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I 
LEV 
For tape files is the same as for NORMAL mode, except 


that the tape is not rewound; i.e., remains at its 
Current position. 


For terminal device files, this indicates that the 
line is not to be hung up, regardless of the specifi- 
cation made at system building. 

a 

UNL 
For tape-resident files the action is the same as for 


NORMAL mode, except that after the rewinding, the tape 
1s unloaded (i.e., cycled down). 


For terminal device files, the line is hung up 
(regardless of the specification made at system 
building time). 


FUNCTION DESCRIPTION: 


The fib address specified by the first argument of this 
macro call can refer to the same structure specified in the 
open file macro call with which this macro call is paired. 


This macro call causes all unwritten buffers to be written, 
records to be unloaded, and the logical end-of-file (EOF) A 
label to be updated. However, the call does not remove the 
file (see the remove file macro call) from the task group 
(l.e., the file remains reserved for the task group and can 

be reopened). 


If the file being closed is a card punch, a file mark card 

is punched. (A card reader/punch is considered to be a card 
punch if the FIB program view word at open time had bit 2 A 
set to 1 (write permitted) and bit 1 set to 0 (read not 
permitted). 


The following information applies only to magnetic tape. 
The actions performed on cloSing a tape file are determined 
by the way the write permit bit (bit 2) in the FIB program 
view word was set when the file was opened. Either an | 
output close (write permission granted) or an input close 
(write permission denied) can be performed. Note that when 
a tape volume is opened for storage management access, and 
both volume and file names were not specified, then no 
trailer labels nor tape marks were written; in that case it 
is the user's responsibility. | 
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1. Output close (write permission): 


ae 


If the file was opened in RENEW mode, the trailer 

label group is written, followed by an end-of-data 
(EOD) tape mark. This action is performed whether 
Or not data records were actually written into the 
file. | 


If the file was opened in PRESERVE mode and write 
operations were performed, the trailer label group 
and EOD tape mark are written. Data and/or files 
located in front of the current poSition of the tape 
are destroyed. | 


If no write operations were performed, or an input 
close is performed (as described below), existing 

data and/or files located in front of the current 

position of the tape are preserved. 


If the LEAVE option is specified, the tape will be 
positioned at the end of the current trailer label 
group. 


2. Input close (no write permission) 


Ae 


If the end-of-file tape mark was detected, the 
trailer label group is processed and the action 
specified by NORMAL, LEAVE, or UNLOAD is taken. 


If the LEAVE option is specified, the tape is posi- 
tioned at the end of the current trailer label 
group. 


If the end-of-file tape mark was not detected, the 
trailer label group is not processed. When the 
LEAVE option is specified, the tape will be misposi- 
tioned. Opening the next file may result in an 
"invalid tape file header" condition. 


The file information block can be generated by a SFIB macro 


call. 


Displacement tags for the FIB can be defined by the 


STFIB macro call. 


NOTES: 


l. If the first argument is coded, the address of 
the FIB is loaded into $B4; if the argument is 
omitted, S$B4 is assumed to contain the address 
of the FIB. 


2. On return, S$R1 contains one of the following 
status codes: | 


C000 -—- No error 
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idle, 


0205 - Illegal argument 
0206 - Unknown or illegal LFN 


0207 - LFN not open 


0225 - Not enough system memory for buffers or 


structures 


C226 - Not enough user memory for buffers or 


structures 
In addition to the above codes, any system 
service codes received by the file manager 
passed on through SRl. 


Example: 


In this example, it is assumed that the file opened in 


example for the open file macro call is to be closed. 
macro call is coded as follows: 


MYFIB DC 5 LFN 5 
CLFILA SCLFIL IMYFIB 


Since the second argument is not specified, the system 
assumes NORMAL mode. 


are 


the 
The 
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COMMAND IN 


CCMMAND_IN 

Macro Call Name: SCIN 
Function Code: 08/02 
Equivalent Command: None 


Read the next record from the standard command-in file for 
the task group of the issuing task. 


FORMAT: 


[label] S$CIN [location of record area address], 
[location of record size], 
[byte offset of beginning of record area] 


ARGUMENT DESCRIPTION: 
location of record area address 


Any address form valid for an address register; pro- 
vides the address of a record area in the issuing task 


into which the next record on the command-in file will 
be placed. 


location of record size 


Any address form valid for a data register; provides 
the size (in bytes) of the record whose address is 
given in argument l. 


byte offset of beginning of record area 
Any address form valid for a data register; provides 


the byte offset of the beginning of the record area 
(from the address provided in argument l). 
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FUNCTION DESCRIPTION: 


This call allows a task to read the next record from the 
Standard command-in file. 


NOTES : ae 


Value 


02 
10 
11 
12 
1A 


The address of the command input record area 
Supplied by argument 1 is placed in $B4; if this 
argument is omitted, $B4 is assumed to contain 
the record area address. 


The record area size supplied by argument 2 is 
placed in SR6; if this argument is omitted, SR6 
is assumed to contain the correct size. 


If argument 3 is L, SR7 is set to zero to deSsig- 
nate that the record area begins in the left 
byte of the specified address. If argument 3 is 
R, SR7 is set to 1 to designate that the record 
area begins in the right byte of the specified 
address. Any other value for argument 3 is 
assumed to designate the location of the byte 
offset to be used, and is placed in SR7. If 
argument 3 is omitted, the record area is 
assumed to begin in the left byte of the speci- 
fied address, and SR7 is set to zero. 


On return, SR1, SR6, SR7, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 


OO0CQ - No error 
0817 - Memory access violation 


All data management read-next-record error 
codes may also be returned. See the 


System Messages manual. 


SR6 - Residual range (number of bytes left 
unfilled in record area). 


SR7 - File type: bits 10 through 15 of $R7 con- 
tain the hexadecimal value for the follow- 
ing file types: : 


File Type 


Fixed relative 
Line/serial printer 
Card reader 

KSR (MDC-connected) 
Bidirectional MLCP 
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Value File Type 


1B BSC 

1E Output-only MLCP 

30 Variable sequential (Spanned records) 

i Relative 

33 Indexed (data) 

34 Indexed (index) 

SB4 - Input record area address 

Example: 


In this example, the issuing task is to read the next record 
of the command-in file into a 128-byte record area whose. 
address is in RECAD. The record area begins at an offset of 
10 bytes from the indicated address. 


INDAD SC IN !RECAD,=128,=10 


RECAD RESV 5+64,0 
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COMMAND LINE PROCESS 


COMMAND LINE PROCESS 
Macro Call Name: SCMDLN 
Function Code: 0C/08 
Equivalent Command: None 


Process the supplied command line by spawning a task to exe- 
cute the command named in the first argument of the macro 
call, and wait for the task's termination. 


FORMAT : 


[label] SCMDLN [location of command line address], 
| [location of command line size] 


ARGUMENT DESCRIPTION: 
location of command line address 


Any address form valid for an address register; pro- 
vides the address of the supplied command line. 


location of command line size 


Any address form valid for a data register; provides 
the size (in bytes) of the command line to be 
processed. 


FUNCTION DESCRIPTION: 


This macro call allows you to embed commands in your pro- 
gram; see the Commands manual. The same task that executes 
the particular command when given from the terminal is 
spawned to execute the command named in the macro call. 


The task spawned of behalf of the macro call is provided 
with a request block that has been constructed by the system 
to contain the edited arguments in system standard task 
request block format. The task that issues this macro call 
waits for the completion of the spawned task before 
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continuing its own processing. The spawned task passes the 
completion status (SR1) to the issuing task. 


NOTES: 1. The address of the command line, supplied by 
argument 1, is placed in SB4; if this argument 
is omitted, S$B4 is assumed to contain the 
address of the command line to be processed. 

2. The size of the command line, supplied by argu- 
ment 2, is placed in SR6; if this argument is 
omitted, SR6 is assumed to contain the size. 


3. On return, SR1 and $B4 contain the following 
information: 


SR1 - Return status; one of the following: 
O000 - No error 


OOQQ0-OOFF - Completion status returned by 
spawned task 


0601 - Insufficient memory 
0602 - Insufficient memory 


0805 - Unbalanced quotation marks, | 
brackets, or parentheses 


O80C - Unresolved symbolic entry 
point 


160A - Invalid bound unit pathname 
for first argument 


160B - Insufficient memory 


FFFF - Honeywell component error pre- 
viously reported | 


SB4 - Address of supplied command line 
Example: 


In this example, the SCMDLN macro call causes a command line 
to be processed which will execute the Assembler to assemble 
the source program MYPROG, residing in the current working 
directory. The Assembler will use 5K words of memory, taken 
from the issuing task group's memory pool, for its symbol | 
table. The assembly listing will be written on the device 
named LPTO1l, and the object unit will be stored in the file 
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MYPROG.O in the working directory. 
already exist, it will be created. 


SCMDLN !LINE, =LENGTH 


LINE TEXT "ASSEM MYPROG -SZ 
LENGTH EQU 2* (S-LINE) 
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Tf MYPROG.O does not 


5 -COUT >SPD>LPTO1' 
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CONSOLE MESSAGE SUPPRESSION 


CONSOLE MESSAGE SUPPRESSION 

Macro Call Name: SCMSUP 

Function Code: 09/02 (suppression), 09/03 (no suppression) 
Equivalent Command: None 


Turn console message suppression on or off for the issuing 
task's task group. 


FORMAT : 
[label] SCMSUP- [keyword] 
ARGUMENT DESCRIPTION: 
keyword 
One of the following values: 


ON - Turn on console message suppression (function 
code 09/02) 


OFF - Turn off console message Suppression (function 
code 09/03) 


If this argument is omitted, OFF is assumed. 


FUNCTION DESCRIPTION: 


This call turns console message suppression on or off for 
the issuing task's task group. 


When console message suppression is turned on, operating 
system components such as storage management will not issue 
error messages to the operator terminal - either directly 
(through the facility offered by the operator information 
message macro call) or indirectly (through the facility 
offered by the report error condition macro call, described 
later in this section). Turning on console message suppres- 
sion does not disable these facilities; rather it prevents 
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the system components from using the facilities to Se a 
anything other than catastrophic errors. 


When console mesSage suppression is turned on, the error 
code normally used in the operator message will be returned 
in SR1l (assuming the message had an error code). 


When console message suppression is turned off, messages are 
again issued in the normal manner. 


NOTE: On return, $R1l contains one of the following subfunc- 
tion codes: 


0002 -— Turn on suppression 
0003 - Turn off suppression 


Example: 


In this example, the issuing task turns on console message 
Suppression for the task group under which it is running. 


SUPON SCMSUP ON 
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CREATE DIRECTORY 


CREATE DIRECTORY 

Macro Call Name: SCRDIR 

Function Code: 10/A0 

Equivalent Command: Create Directory (CD) 


Creates a new directory in the file system hierarchy. This 
function is typically done outside of program execution. 


FORMAT : 


[label] SCRDIR [argument structure address] 


ARGUMENT DESCRIPTION: 


argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


pathname pointer 


A 4-byte address which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII "space" char- 
acter) that, when expanded, identifies the 
directory in the hierarchy in which to create 


the new directory and the name of the new direc- 
tory itself. 


reserved 


A 4-byte entry containing "zeros." 


FUNCTION DESCRIPTION: 


This request can be used only to create new directories, 
which are created with: 
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x ie 
i og 
a 


An initial allocation of eight physical sectors (allowing 
32 entries) for diskette, eight physical sectors (allow- 
ing 64 entries) for cartridge disk and storage module 
(except 19-surface, 200 tracks-per-inch), or 16 physical 
sectors (allowing 128 entries) for 19-surface, 200 
tracks-per-inch storage module. 


An increment allocation of four physical sectors (allow- 
ing 16 entries each) for diskette, eight physical sectors 
(allowing 64 entries) for cartridge disk and storage 
module (except 19-surface, 200 tracks-—per-inch), or 16 
physical sectors (allowing 128 entries) for 19-surface, 
200 tracks-per-inch storage module). 


A maximum allocation of 4000 physical sectors (allowing a 
maximum of 16,000 entries) for diskette, or 4000 physical 
Sectors (allowing a maximum of 32,000 entries) for car- 
tridge disk and storage module. 


NOTES: 1. If the argument is coded, the address of the 


parameter structure is loaded into $B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the parameter structure. 


2. On return, SR1 contains one of the following 
Status codes: 


0000 - Successful completion 

0201 - Illegal pathname 

0205 - Illegal argument 

0209 - Same named subdirectory not found 
O020C - Volume not found 


O212 - Attempted creation of existing file or 
directory 


0215 - Not enough contiguous logical sectors 
available 


0222 - Pathname cannot be expanded, no working 
directory 


0224 - Directory space limit reached or not 
expandable 


0225 - Not enough system memory for buffers or 
Structures 
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0226 - Not enough user memory for buffers or 
structures 


022C - Access control list (ACL) violation 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SR1. 


Example: 


In this example, the macro call is used to create the sub- 
directory, labeled SUBINDEX.A, identified in the create file 
example. This subdirectory must exist before the path iden- 
tified in that example (i.e., VOLO3 SUBINDEX.A FILE A) can 
be used. Prior to issuing the create directory macro call, 
the following parameter structure and pathname must exist: 


SUBDIR DC <DIRPTH 
RESV 2-SAF 
RESV 2,0 
DIRPTH DC 'AVOLO 3>SUBINDE X.AA' 


The macro call can be specified as follows: 


SCRDIR 'SUBDIR 
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CREATE FILE 


CREATE FILE 

Macro Call Name: SCRFIL 

Function Code: 10/30 

Equivalent Command: Create File (CF) 


Creates a new disk file by placing a description of the file 
in the file system hierarchy and, optionally, allocating 
Space for it. The user identifies this file by either a 
logical file number (LFN) a pathname, or both. At the 
completion of create file execution, the file is reserved 
exclusively for the task group. If both an LFN and pathname 
are supplied then, in addition to creating and reserving the 
file, it is assigned to the LFN. Subsequent macro calls 
(open file, read record, etc.) can then be directed to the 
file via this LFN. SCRFIL can be used to create any of 

the disk files which are described in the Data File 


Organizations and Formats manual, including: 


Fixed-Relative 
Relative 
Sequential 
Indexed 


O00 0 


In addition SCRFIL can be used to create a temporary disk 
file which will exist only during this task group's 
execution. This function is normally done outside program 
execution. 
FORMAT : 

[label] SCRFIL [parameter structure address] 
ARGUMENT DESCRIPTION: 


Parameter Structure address 


Any address form valid for an address register; pro- 
vides the location of the parameter structure defined 
below. The parameter structure must contain the fol- 
lowing entries in the order shown. 
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logical file number ees 


A 2-byte logical file number (LFN) used to refer 
to the file. It must be a binary number in the 
range 0 through 255, ASCII blanks (2020) which 
indicates that an .LFN is not specified, or -l 
(FFFF), which indicates that the system should 
assign an LFN from the pool of available LFNs. 


pathname pointer 


A 4-byte address of the pathname, which may be 
any address form valid for an address register; 
points to a pathname (which must end with an 
ASCII space character) that, when expanded, 
identifies (1) the name of the file to be 
created, and (2) the directory in the file sys- 
tem hierarchy in which to add the name and 
attributes of the file. Binary zeros (null 
pointer) in this entry indicate that a path is 
not specified; if the path identified is a 
Single ASCII space (20) character, the file 
being created is a temporary file. 


file organization 


A l-byte field specifying the file organization, 
as follows: 


2 - Fixed-relative without deletable 
records 


5 - Fixed-relative with deletable records 
R - Relative | 

S - Sequential 

I - Indexed 


reserved 


This l-byte field must contain zeros. 
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logical record size 


A 2-byte value that specifies the length of the 
longest logical record in the file. If the file 
organization entry, above, specified R, S, or I, 
this size does not include headers. If the file 
organization entry specified 5, the size 
includes the 2-byte record header. There are no 
headers for a file organization shown as 2. 


control interval size 


A 2-byte value that specifies the unit of file 
space allocation, as follows: 


For fixed-relative files: defines only the 
unit of space allocation and can be speci- 
fied as any multiple of 128 bytes which. 
includes both CI and logical record header 
information. 


For all other files: defines the size of a 
data transfer to/from main memory (and thus 
the buffer size); must be Specified as a 
multiple of 256 bytes, including CI and 
logical record header information. | 


il, 


Zeros in this entry result in a size of 512 
bytes. 


initial allocation size 


A 2-byte value that specifies the number of con- 
trol intervals to be allocated to the file at 
File-creation time; zeros in this entry indicate 
that no space is to be allocated initially. 


allocation increment size 


A 2-byte value that specifies the number of 
additional control intervals to be dynamically 
allocated to the file at load time if the number 
specified in the “initial allocation size" entry 
are filled. Zeros in this entry indicate a 
value of 40 physical sectors. 


maximum allocation size 
A 2-byte value that specifies the maximum number 
of control intervals that can be allocated to 


the file. Zeros in this entry indicate that 
( there is no limit. 
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free space per control interval 


A 2-byte value, as follows: 


For indexed files: The number of bytes to be 
left free in each control interval at file- 
loading time; this permits records to be 
inserted in the file without cauSing overflow. 


For all other file organizations: Contains 
zeroS. 


fi local overflow allocation increment 


A 2-byte value that sets the frequency at which 
a local overflow control interval will be allo- 
cated when an indexed file is loaded. For 
example, if this value is 10, one local overflow 
control interval will be allocated after every 
ten data control intervals are allocated. 


number of key descriptors 


A 2-byte value, as follows: 


pointer 


A 


reserved 


For indexed files: Must contain Z'0001' 


For all other file organizations: Contains 
zeros. | } 


to key descriptor 
4-byte address, as follows: 


For indexed files: Any address form valid for 
an address register; points to a key descrip- 
tor structure that defines the key field in 
records stored in an indexed file. This 
Structure is described below. 


For all other file organizations: Contains 
zeros. 


An 8-byte entry containing zeros. 


The key- 


descriptor structure pointed to by the pointer 


to key descriptors entry in the argument structure 
described above must contain the following entries in 


the order shown: 
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record type range 

A 4-byte value that must contain Z'OOOOFFFF'. 
number of key components 

A 1l-byte value that must contain the value l. 
reserved 

A 9-byte entry containing zeros. 
key component data type 


A l-byte entry that contains an ASCII C for 
character data or D for decimal data. 


key component size 


A l-byte binary value that specifies the length 
of the key field in the record. 


key component offset 


A 2-byte binary value that specifies the number 
of bytes from the beginning of the record to the 
beginning of the key field; the first byte in 
the logical record is position l. 


FUNCTION DESCRIPTION: 


This macro call cannot be issued if the file already exists 
(i.e., a create file macro call with the same pathname has 
been previously issued and the file has not been released), 
or if the LFN is currently assigned to an open file in the 
Same task group. When properly coded, the create file macro 
call allocates space to the specified file in accordance 
with the entries in the argument structure (i.e., it 
"creates" an empty file, which can be loaded with data 
through data management or storage management macro calls). 


The file can be specified (in the argument structure) by (1) 
an LFN only, (2) a pathname only, or (3) both an LFN and a 
pathname. 


o If only an LFN is specified, it must previously have been 


associated with a pathname (See the associate file macro 
call. 
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o If only a pathname is specified (i.e., the LFN field con- 
tains ASCII spaces (2020)), the file is reserved without 
a unigue LFN. The only requests that can use the files 
are those that can refer to it by pathname only. If a 
pathname is specified, and the LFN field contains a value 
of -l (FFFF), the system assigns a unique LFN; it is the 
user's responsibility to return the LFN to the pool of 
available LFNs (via remove file macro call) when it is no 
longer needed. The unique LFN is assigned from the pool 
of available LFNs for the task group. The highest LFN 
not already assigned is set in the LFN entry of the argu- 
ment structure, overlaying the previous contents (FFFF). 
You must move this value to other structures (i.e., argu- 
ment structures of FIBsS) as required. 


o If both an LFN and a pathname are specified, then (in 
addition to creating the file), the file is assigned to 
the specified LFN. 

Zeros are specified in the "initial allocation size" entry, 
space is allocated according to the value specified in the 
"allocation increment size" entry at file load time. 


Initial allocation and allocation increment sizes (although 
stated in terms of control intervals) cannot resolve to a 
value greater than 8191 logical sectors for mass storage 
units, and 8191 physical sectors for diskettes and cartridge 
disks. After the space is allocated, the system reserves it 
with "exclusive" concurrency control; as a result, it is not 
necessary to issue a get file macro call before an open file 
macro call in order to access the file exclusively. If the 
file being created is a temporary file (see the "pathname 
pointer" entry described in the argument structure descrip- 
tion), it can be released (i.e., deleted) through the remove 
remove file macro call. 


Offset tags for the parameter structure can be defined by 
the SCRPSB macro call. 


NOTES: 1. If the argument is coded, the address of the 
argument Structure is loaded into SB4. If the 
argument is omitted, $B4 is assumed to contain 
the address of the argument structure. 


2. On return, S$R1 contains one of the following 
Status codes: 


0000 - No error 


0201 - Illegal pathname 
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0205 - Illegal argument 

0206 —- Unknown or illegal LFN 

0208 - LFN or file already open 

0209 - Same named subdirectory not found 
O020C - Volume not found 

O211 - Unable to establish unique LFN 

0212 - Attempted creation of existing file 


0215 - Not enough contiguous logical sectors 
available 


0222 - Pathname cannot be expanded, no working 
directory 


0224 - Directory space limit reached or not 
expandable 


0225 - Not enough system memory for buffers or 
control structures 


0226 - Not enough user memory for buffers or 
control structures 


022C - Access control list violation 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In this example, the argument structure labeled FILE A, 
defined under "Assumptions for File System Examples" in 
Section 3, describes the file to be created. In addition, 
the following key descriptor structure has been defined: 


KEY DC Z'OOOOFFFF' RECORD TYPE RANGE 
DC Z*0100! NO. OF COMPONENTS = 1 
RESV 4,0 RESERVED 
DC Z"430A' KEY COMP. DATA TYPE = C; 
KEY LENGTH = 10 
DC i KEY LOC. IN RECD. = FIRST POSITION 
Also, the pathname was defined as follows: 
IDXOl DC  '*VOLO03>SUBINDEX.A>FILE AA' 
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With the preceding definitions having been made, the 
lowing macro call will create FILE A: 


DOM YAA SCRFIL IFILE A 


fol- 
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CREATE FILE PARAMETER 
STRUCTURE BLOCK-OFFSETS 


CREATE FILE PARAMETER STRUCTURE BLOCK —- OFFSETS 


Macro Call Name: SCRPSB 
Associated Macro Call: SCRFIL 
Generated Offsets Tags: 


Corresponding 


Offsets 
Tag (in Words) Entry Name 
R LFN 0 Logical file number (LFN) 
R_ PTHP +1 Pointer to path 
R ORG +3 File organization (first byte) 
R RFU +3 Reserved (second byte) 
R LRSZ +4 Logical record size 
R CISzZ +5 Control interval size 
R IASZ +6 Initial allocation size 
R AISZ +7 Allocation increment size 
R MASZ +8 Maximum allocation size 
R_ FREE +9 Amount of free space per C.I. 
R LOV +10 Local overflow allocation increment 
R NKD +11 Number of key descriptors 
R KDP +12 Pointer to key descriptors (see SGIKBD 
a macro call) 
R_ SZ +18 Size of structure (in words); not a 


field in the block 
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CREATE GROUP 


CREATE GROUP 


Macro Call Name: S$CRGRP 


Function Code: 0D/02 


Equivalent Command: Create Group (CG) 


Define a new task group. Allocate and initialize the data 
structures required to control the task group within the 


specified memory pool. Create the lead task as described 
under the create task macro call. 


FORMAT : 


[label] 


SCRGRP [location of group identifier], 
[location of memory pool identifier], 
[location of base level], 
[location of high logical resource number], 
[location of high logical file number], 
[location of root entry name address] 


ARGUMENT DESCRIPTION: 


location of group identifier 


Any address form valid for a data register; provides 
the group identification of the new task group. The 
group identifier must be a two-character (ASCII) name 
that does not have the $ character as its first 
character. 


location of memory pool identifier 


Any address form valid for a data register; provides 
the identifier of the memory pool to be used to 
satisfy all memory requests emanating from the created 
task group. The memory pool identifier consists of 
two ASCII characters that name a pool defined at sys- 
tem building. If this argument is omitted, the new 
task group will use the memory pool associated with 
the issuing task group. 
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location of base Level 


Any address form valid for a data register; provides 


the base priority level, relative to the system level, 
at which the lead task will execute. 


A base level of 0, if specified, is the next higher 
level above the last system priority level. The sum 
of the highest system physical level plus 1, and the 
base level of a group, and the relative level of a 
task within that group, must not exceed 62,0, 


location of high logical resource number 


Any address form valid for a data register; provides 
the highest logical resource number (LRN) that will be 
used by any task in the task group. The LRN can be a 
value from 0 through FC (hexadecimal). If this argu- 
ment is omitted, or if the value specified is less 
than the highest LRN used by the system task group, 
the system task group's LRN will be used. 


location of high logical file number 


Any address form valid for a data register; provides 
the highest logical file number (LFN) to be used by 
any task in the task group. The LFN can be a value 
from 0 through FF (hexadecimal). If this argument is 


omitted, the value 15 is assumed. (Refer to the asso- 
ciate file macro call.) 


location of root entry name address 


Any address form valid for an address register; pro- 
vides the address of the root entry name string that 
specifies the pathname of the bound unit to be exe- 
cuted as the lead task. The bound unit pathname can 
have an optional suffix in the form of ?Pentry, where 
entry is the symbolic start address within the root 
segment. If this suffix is not given, the default 
Start address (established at Assembly or Link time) 
is used. EC?ECL specifies the command processor as 
the lead task. 


FUNCTION DESCRIPTION: 


This call causes the initialization and allocation of all 
data structures used by the system to define and control the 
execution of a task group. It causes the loading of the 
root segment of the lead task of the task group. It does 


not cause the system to activate any task within the task 
group. 
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NOTES: 


The group identifier supplied by argument l is 


placed in SR2; 


if this argument is omitted, SR2 


is assumed to contain the group identifier to be 


used. 


The memory pool identifier supplied by argument 


2 is placed in SR4; 


SR4 is set to zero to indicate that the memory 
pool of the issuing task group should be used by 
the newly created task group. 


The base priority level supplied by argument 3 


is placed in SR5; 


if this argument is omitted, 


SR5 is assumed to contain the base priority 
level to be used. 


The high LRN value supplied by argument 4 is 


placed in SR6; 


if this argument is omitted, SR6 


is set to zero to indicate that the value of the 
highest LRN created for the system task will be 


used. 


The high LFN value specified by argument 5 is 
placed in SR7; if this argument is omitted, $R7 


is set to 15. 


The address of the root entry name supplied by 


argument 6 is placed in $B2; 


omitted, S$B2 is assumed to contain the address 


if this argument is 


of the bound unit to be executed by the lead 


task. 


On return, 


SR1l and $R2 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 
0601 
0602 
0804 
0806 
0807 
0808 
0809 
O80A 
080C 
160A 
160B 


No error 

Insufficient memory 
Insufficient memory 
Group id in use 

Invalid group id 

Invalid memory pool identifier 
Invalid base level 
Invalid high LRN 

Invalid high LFN 
Unresolved start address 
Invalid pathname 
Insufficient memory 


SR2 - Group id of created group 


CBO08 


if this argument is omitted, 


Example: 


In this example, a new task group is created with a group id 
of Gl; the group uses memory pool Pl, and has level 40 
(decimal) assigned as a base level. Both the high LRN and 
high LFN are defaulted (only a number of LRNsS equivalent to 
that configured for the system task group will be available, 
and the highest logical file number available will be 15 
decimal). The task group's lead task will begin its execu- 
tion at the entry point ENTRY1 of the bound unit PROG], as 
found by application of the system search rules. 


GROUP1 SCRGRP ='Gl',='P1',=40,,,!ROOT 


ROOT TEXT "PROG1?ENTRY1LA' 
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CREATE OVERLAY AREA TABLE 


CREATE OVERLAY AREA TABLE 
Macro Call Name: SCROAT 
Function Code: 07/0A 

Equivalent Command: None 


Create an overlay table to be used with overlay loading 
functions that require a pointer to an overlay area table 
(OAT). The overlay area described by this OAT is created in 
real memory space. (See the Programmer's Reference manual 
for details on overlays and overlay area tables.) 


FORMAT: 


[label] SCROAT [location of OAT address], 
[location of size of overlay area entry], 
[location of number of overlay area entries] 


ARGUMENT DESCRIPTION: 


location of OAT address 


Any address form valid for an address register; pro- 
vides the location into which the system will place 
the address of the OAT. 


location of size of overlay area entry 


Any address form valid for a data register; provides 
the location of a value specifying the number of words 
to be contained in each entry in this overlay area. 
This value should be equal to or greater than the size 
of the overlays to be placed in the area for loading. 


location of number of overlay area entries 


Any address form valid for a data register; provides a 
value specifying the number of entries in this overlay 
area. (The size of each entry is defined by argument 
2.) The value for this argument depends on the number 
of overlays of this size used by the bound unit and 
the frequency of their release. 
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FUNCTION DESCRIPTION: 


This macro call creates an overlay area table (OAT) to be 
used by subsequent loader functions that require (or imply) 
the existence of an OAT in the call. 


The real memory space for the overlay area described by this 
call is obtained from the same memory pool used by the cur- 
rent bound unit of the issuing task. If the current bound 
unit is not sharable, memory will be obtained from the pool 
associated with the group of the issuing task. If the cur- 
rent bound unit is sharable, memory will be obtained from 
the system pool. 


Once allocated, the overlay area table becomes a supporting 
resource of the current bound unit. That is, an OAT queue 
header field will be added to the definition of the bound 
unit descriptor, and as OATS are created, they will be 
placed in this queue. The OAT queue is maintained so that 
OATS are ordered by ascending area size. 


Before an OAT is allocated, any existing OATs are searched 
for an OAT with area size equal to that specified in argu- 
ment 2. If one is found equal, the number of areas in this 
OAT is returned to the caller (i.e., location specified in 
argument 1 or to register $R6). On return, the caller 
receives the address of the newly created OAT or an existing 
OAT. 


The overlay area reserve and execute overlay (SOVRSV) and 
overlay area, release (SOVRLS) macro calls require that 
overlay areas be present. If no OAT that controls entries 
of the specified size can be found, the system creates an 
overlay area with the number of entries specified by argu- 
ment 2, and then creates the controlling OAT. 


When the system returns the address of the OAT, it also 
returns the actual size of the overlay area and the actual 
number of areas allocated or already present. 


NOTES: 1. The address of the OAT is returned in SB4 and is 
stored aS specified in argument 1. If argument 
1 is omitted, the address is stored only in $SB4. 


2. The size of the entry supplied by argument 2 is 
placed in $R2; if this argument is omitted, SR2 
is assumed to contain the correct size. 


3. The number of entries supplied by argument 3 is 


placed in $R6; if this argument is omitted, SR6 
is assumed to contain the correct number. 
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4. On return, S$R1l, $R2, S$R6, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 
0000 — No error 


1602 - Invalid argument (size or number of 
overlay areas) 


160A - Insufficient memory 


SR6 - Actual number of overlay areas allocated 
to this area (if S$R1 is 0000) 


SB4 - Address of OAT (if S$R1 is 0000) 


5. On a return with error, the contents of S$R2, 
SR6, and SB4 are unspecified. 


Example: 

In this example, an overlay area of three 512-word entries 
is created. (It is assumed that no existing overlay area 
table controls 512-word entries.) The address of the con- 
trolling OAT will be placed in OATAD. 


OATAD RESV 2,0 
SCROAT =OATAD,=512,=3 


5=62 CBO08 


i, 


CREATE TASK 


Macro Call Name: SCRTSK 


CREATE TASK 


Function Code: O0C/0O2 (same bound unit), 
0C/03 (different bound unit) 


Equivalent Command: 


Create Task (CT) 


Add the supplied task definition to the set of currently 
defined tasks within the task group of the issuing task. 


FORMAT: 


[label] SCRTSK 


[location 
[location 
[location 
[location 


ARGUMENT DESCRIPTION: 


of 
of 
of 
of 


logical resource number], 
relative priority levell, 
start address], 

root entry name address] 


location of logical resource number 


Any address form valid for a data register; provides 
the location of the logical resource number (LRN) by 
which the issuing task group can refer to the created 


task. The LRN 


(a value from 0 through 252) cannot 


exceed the value used as the high LRN in the create 
group macro call that created the group of which this 
task is a member. 


location of relative priority level 


Any address form valid for a data register; provides 
the location of the priority level, relative to the 
task group's base priority level, at which the created 
task is to execute. 
-l1, the priority level used is that of the issuing 


task. 


If 


this argument is omitted or is 
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location of Start address 


Any address form valid for an address register; pro- 
vides the location of the task start address when the 
newly created task is to execute in the same bound 
unit as the task that issued the create task macro 
call. (Function code 0C/02.) 


location of root entry name address 


Any address form valid for an address register; pro- 
vides the address of the pathname of the bound unit 
root segment to be loaded for execution by the newly 
created task. The bound unit pathname can have an 
optional suffix in the form of ?entry, where entry is 
the symbolic start address within the root Segment. 

If this suffix is not given, the default start address 
(established at Link time) is used. (Function code 
0C/03.) 


FUNCTION DESCRIPTION: 


This call causes the allocation and initialization of the 
data structures that define and control task execution. The 
call does not activate the task; the request task macro call 
is required for task activation. 


One or more create task macro calls can be issued to create 
one or more tasks within a task group. 


When a create task macro call is executed, the system builds 
a resource control table (RCT) and a task control block 
(TCB) for the created task. The address of the RCT is 
placed in the logical resource table (LRT) in association 
with the appropriate LRN. | 


Either the location of the start address or the location of 
the root entry name address, but not both, can be specified. 


If the new task is to execute within the bound unit of the 
issuing task, then the count of tasks associated with the 
unit is incremented (function code O0C/02) to prevent pre- 
mature reuse of memory containing the bound unit. 


If the specified bound unit is not a sharable bound unit 
that is currently resident in memory, the root segment of 
the bound unit is loaded into memory belonging to the task 
group. If the specified bound unit is both sharable and 
currently resident, the count of tasks associated with the 
unit is incremented. (Function code O0C/03.) 
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NOTES: 


The LRN supplied by argument 1 is placed in $R2; 
if this argument is omitted, SR2 is assumed to 
contain the LRN for the created task. 

The relative priority level Supplied by argument 
2 is placed in SR6; if this argument is omitted, 
SR6 is set to the relative priority level of the 
task issuing this create macro call. 

Arguments 3 and 4 are mutually exclusive. If 
both are supplied, argument 3 is used and a 
diagnostic is issued. Information derived from 
either argument is placed in $B2; if these argu- 
ments are omitted, SB2 is assumed to contain the 
start address to be used. 


On return, SR1 and SR2 contain the following 
information: 


SR1 - Return status; one of the following: 
0000 - No error 
Olxx - Media error 
0209 - Bound unit not found 
0809 -—- LRN too large 


0813 - Referenced LRN already in use or 
invalid 


0827 - Bound unit file not fixed-relative 
1604 - Unresolved symbolic start address 
160A - Insufficient memory 

l6lj1] - Zero length root segment 

1613 - Invalid bound unit pathname 

1615 - Illegal bound unit file 


SR2 — LRN of created task 
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Examples: 


In this example, the SCRTSK macro call makes a task known as 
logical resource number 10 (decimal) of the issuing group. 
The task will execute at priority level 2 relative to the 
group's base level. The task will execute the procedures 
contained in the bound unit PROG10O, as found by application 
of search rules, entering the bound unit at entry point 
PROG1O. 


SCRTSK =10,=2,,!ROOT 


ROOT TEXT 'PROG1OA' 


In this example, the SCRTSK macro call makes a task known as 
logical resource number 12 (decimal) of the issuing group. 
The task will execute at the same priority level as the 
issuing task. The task will execute the same bound unit as 
the issuing task and will be started at the address repre- 
sented by the label SSA. 
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DEFINE SEMAPHORE 


DEFINE SEMAPHORE 

Macro Call Name: SDFSM 
Function Code: 06/04 
Equivalent Command: None 


Define a Semaphore for the issuing task group; assign the 
semaphore an identifier and an initial value. 


FORMAT : 


[label] SDFSM [location of Semaphore identifier], 
[location of initial value of semaphore] 


ARGUMENT DESCRIPTION: 
location of Semaphore identifier 


Any address form valid for a data register; provides 
the two ASCII characters that identify this semaphore. 


location of initial value of semaphore 


Any address form valid for a data register; provides 
the initial value to which the semaphore is set. This 
value specifies the number of simultaneous requests 
for the resource identified by the semaphore. If this 
argument iS omitted, the initial value of the sema- 
phore is set to one (one user at a time). 


FUNCTION DESCRIPTION: 


This call allows different tasks within the same task group 
to coordinate the use of a resource (Such as taSk code, a 
device, or a file). The semaphore acts as a gating mecha- 
nism that allows a requesting task to obtain the use of a 
resource if the value of its associated semaphore is 
positive. 
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When a semaphore is defined by a task, it is available only 
to tasks within the task group of the defining task. See 
"Semaphore Functions" in Section 2 for a discussion of 
semaphores. 


The 2-character semaphore identifier indicated by argument 1 
is a system symbol used by the monitor to coordinate 
requests for the reSource being controlled. The initial 
value indicated by argument 2 specifies the type of control 
to be exercised. If this value is 1, the resource can be 
accessed by only one task at a time. A value of 2 allows 
two users, 3 three users, and So on. 


NOTES: 1. The semaphore identifier supplied by argument 1 
1s placed in $R6; if this argument is omitted, 
SR6 is assumed to contain the identifier to be 
used. 


2. The initial semaphore value supplied by argument 
2 is placed in S$R2; if this parameter is 
omitted, $R2 is set to l. 


3. On return, $R1 and $R6 contain the following 
information: 


SR1 - Return status; one of the following: 
OO000 - No error 


0503 - Semaphore id previously defined in 
issuing task group 


SR6 - Semaphore identifier (as supplied) 
Example: 


In this example, the SDFSM macro calls define two semaphores 
named TH and LK. 


TH 1S a semaphore having an initial value of 10 and which 
controls the allocation of ten identical nonsharable 
resources, Such as magnetic tape drives, that are called 
"resources" in this example. Any task wanting a resource 
does a P-op (See reserve resource) on this Semaphore. If no 
resources are available at the moment, the task is suspended 
until a resource becomes available. When a task finishes 
uSing a resource, it does a V-op (see releaSe semaphore) , 
thereby making the resource available for use by other 
tasks. If any other task is waiting for this semaphore when 
the V-op is done, the task that was waiting the longest is 
awakened. 
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LK 1S a semaphore which has an initial value of 1 and which 
controls access to the free reSource list by Serving as a 
lock. After a task has reserved the right to use a reSource 
by performing the P-op on TH as described above, the task 
will unlink (the description of) a particular resource from 
the free-resource list. Upon entering a Section where it 
examines or modifies the free-resource list, the task does a 
P-op on the semaphore LK, thus enSuring the integrity of 
this data base. After it stops uSing this data base, the 
task does a V-op on LK. 


When the task finishes using the resource, it will return 
the resource by doing a P-op on LK, linking (the description 
of) the resource being returned into the free-resource list, 
Going a V-op on LK, and then doing a V-op on TH. 
DEFINE SEMAPHORES TO CONTROL RESOURCES 
SDF SM ='TH',=10 
SDFSM ='"LK' 


e 
e 


ROUTINE TO GET A RESOURCE 

FIRST GET RIGHTS TO TAKE A RESOURCE 
SRSVSM ='TH! 

NOW LOCK THE FREE RESOURCE LIST 
SRSVSM =" 1K * 


TAKE A RESOURCE FROM THE FREE RESOURCE LIST 


THEN UNLOCK THE FREE RESOURCE LIST 
SRLSM ="LK' 

END OF ROUTINE TO GET A RESOURCE 

ROUTINE TO RETURN A RESOURCE 

FIRST LOCK THE FREE RESOURCE LIST 


SRSVSM ='LK' 
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NOW LINK THE RESOURCE BACK INTO THE FREE RESOURCE LIST 


e@ 
e 


THEN UNLOCK THE FREE RESOURCE LIST 
SRLSM =" 
FINALLY RELEASE THE RESOURCE 
SRLSM aT H 


END OF ROUTINE TO RETURN A RESOURCE 
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DELETE GROUP 


DELETE GROUP 

Macro Call Name: SDLGRP 

Function Code: O0D/04 

Equivalent Command: Delete Group (DG) 


Mark the task group as eligible for deletion when it becomes 
dormant; then return all allocated memory to the associated 
memory pool. 


FORMAT: 

[label] SDLGRP [location of group identifier] 
ARGUMENT DESCRIPTION: 
location of group identifier 


Any address form valid for a data register; provides 
the group identification of the task group to be 
deleted. This task group must have previously been 
created by a create group macro call. If this argu- 
ment is omitted, the issuing task group is deleted. 


FUNCTION DESCRIPTION: 


This call removes all data structures, built by the create 
group macro call issued with this group id, when the group 
becomes dormant. No further enter group request macro 
calls can be issued for this task group once the delete 
group macro call has been issued. 


When a task group is deleted, the memory occupied by the 
data structures defining the group, and any memory asso- 
ciated with the execution of the group, is returned to the 
appropriate memory pool. 
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The delete group macro call takes effect immediately if the 
task group is dormant when the command is issued. If the 
task group is active (i.e., its code is being executed and/ 
or. there are requests in its request queue), the delete 
group macro call takes effect when execution terminates and 
no requests remain in the queue. 


NOTES: ae 


Example: 


The group id supplied by argument 1 is placed in 
SR2; if this argument is omitted, S$R2 is set to 
zero to designate that the issuing task group is 
to be deleted. 


On return, SR1 and SR2 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 - Delete task group status set 
0806 - Task group not found 


SR2 - Group id of deleted task group 


In this example, the SDLGRP macro call causes the task group 
in which the macro call is executed to be deleted when the 
group's tasks are all terminated with no queued group ., 


requests. 


NOABA SDLGRP 
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DELETE RECORD 


DELETE RECORD 
Macro Call Name: SDLREC 


Function Code: 11/30 (current), 11/31 (key) 


Equivalent Command: None 


Removes the specified logical record from the file; valid 
for all file organizations except fixed-relative without 
deletable records, tape-resident sequential files, and 
device files. 


FORMAT: 


[label] S$DLREC [fib address] Cee) 


ARGUMENT DESCRIPTION: 
fib address 


Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). 


— 
CUR 


Indicates that the record read by the immediately pre- 
ceding read next or read with key (i.e., the last 
record read; see “Read Record") macro call is to be 
deleted. (This is the default value for this macro 
call.) You must code the following FIB entry: 


logical file number 
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KEY 


Indicates that the record identified by the key value 
pointed to by the FIB is to be deleted. You must code 
the following FIB entries: 


logical file number 
input key pointer 
input key format 


FUNCTION DESCRIPTION: 


Before this macro call can be executed, the file must have 
been opened (see the open file macro call) with a program 
view word that allows access via data management (bit 0 is 
0) and allows delete operations (bit 4 is 1). The file must 
have been reserved (see get file macro call) with write 
access concurrency (type 3, 4, or 5). In addition, execu- 
tion of this macro call has no effect on the next read or 
write pointer (i.e., it can be issued between a read next 
record and write next record macro call without disturbing 
the sequence of the records being read or written). 


The delete record macro call does not apply to fixed- 
relative files with nondeletable records, tape files, and 
device files. , 


The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined by the 
STFIB macro call. 


NOTES: 1. If the argument is coded, the address of the FIB 
is loaded into S$B4; if the argument is omitted, 
SB4 is assumed to contain the adéeress of the 
FIB. 


2. None of the out-values in the FIB are set by 
this macro call. 


3. On return, $R1 contains one of the following 
Status codes: 


O000 - No error 

0203 - Illegal function 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 

0207 - LFN not open 

O20A - Address out of file 

O20E - Record not found 

0217 - Access violation 

0219 - No current record pointer 
O21E - Key length or location error 
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O22A - Record lock area overflow 
022B - Requested record is locked 


In addition to the above codes, any system 
service codes received by the data manager are 
passed on through SRl. 


Example: 


The macro call in this example identifies the FIB that is 
described under "Assumptions for File System Examples" in 
Section 3. The STFIB macro call reserved the FIB tags. The 
SDLREC macro call indicates that the current record is to be 
deleted; it is assumed that the file is open and that a 
SRDREC NEXT (read next record) macro call immediately 
precedes the SDLREC macro call. The macro call is: 


SDLREC IMYFIB,CURRENT 
The FIB identified by the address in the first argument is 
as defined in the example for the open file macro call. In 


addition, offset tags can be used to access the LFN in later 
instructions in your program with the macro call STFIB. 
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DELETE TASK 


DELETE TASK 

Macro Call Name: SDLTSK 

Function Code: 0C/04 

Equivalent Command: Delete Task (DT) 


Delete the definition of a task from the task group of which 
the task issuing this macro call is a member. 


FORMAT: 


[label] SDLTSK [location of logical resource number] 
ARGUMENT DESCRIPTION: 


location of logical resource number 


Any address form valid for a data register; provides 
the location of the LRN of the task to be deleted. 
The LRN (a value from 0 through 252) must have been 
specified in a previously issued create task macro 
call. If this argument is omitted, the task issuing 
the macro call is deleted. 


FUNCTION DESCRIPTION: 


This call removes the data structures constructed by the 
create task macro call that was issued with the specified 
LRN. 


If the task is executing, the macro call causes its defini- 
tion to be deleted when the task next issues a terminate 
macro call and there are no request blocks in its request 
queue. No further request task macro calls can be issued 
for this task after the delete task macro call has been 
issued. | 
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If the task is not executing and there are no outstanding 
requests for it, its definition is deleted immediately. 
When the task is deleted, the memory occupied by its data 
structures is returned to the appropriate memory pool. The 
delete task function operates asynchronously. The issuing 
task does not wait until the referenced task is deleted. 


NOTES: 1. The LRN specified by argument 1 is placed in 
SR2; if this argument is omitted, $R2 is set to 
-l to denote that the task issuing the macro 
call is to be deleted. 


2. On return, $R1 and S$R2 contain the following 
information: 


SR1 - Return status; one of the following: 


OO00 - No error 
0802 - Invalid LRN 


SR2 -— LRN of deleted task 
Example: 


In this example, the SDLTSK macro call causes the task known 
as logical resource number 10 (decimal) within the issuing 
task's task group to be deleted. If the SDLTSK macro call 
shown in this example was executed in the same task group as 
the SCRTSK macro call used in the first example of the 
create macro call description, the task created by that 
example would be deleted. 


DEL AA SDLTSK =10 
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DISABLE DEVICE ON ATTENTION 


DISABLE DEVICE ON ATTENTION (MOD 400 ONLY) 
Macro Call Name: SDSDV 

Function Code: 02/02 

Equivalent Command: None 


Disable the specified device when an attention interrupt 
occurs. 


FORMAT: 


[label] SDSDV [location of LRN] 
ARGUMENT DESCRIPTION: 


location of LRN 


Any address form valid for a data register; provides 
the location of the logical resource number (LRN) of 
the device to be disabled. The LRN must be a system 
LRN (defined at system building). 


FUNCTION DESCRIPTION: 


This call sets the device status to disabled when an atten- 
tion interrupt occurs. It is typically used to ensure that 
volume Swaps are detected by the application program. 


A disabled device is logically unavailable and returns a 
0108 status until enabled. To regain use of the device, you 
must enable it (see the enable device macro call) each time 
an attention interrupt occurs. 


NOTES: 1. The LRN specified by argument 1 is placed in 
SR2; if this argument is omitted, S$R2 is assumed 
to contain the correct LRN. | 


2. On return, S$R1 and $R2 contain the following 
information: 
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SR1 - Return status; one of the following: 


0000 -—- No error 
0102 - Invalid LRN 


SR2 - LRN of device 


Example: 


In this example, the SDSDV macro call is used to disable the 
device whose LRN is 15 whenever an attention interrupt 
occurs. 


DISPT SDSDV =15 
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DISABLE USER TRAP 


DISABLE USER TRAP 

Macro Call Name: SDSTRP 
Function Code: 0A/02 
Equivalent Command: None 


Disable the handling of the specified trap for the issuing 
task. 


FORMAT : 


[label] SDSTRP [location of trap number] 


ARGUMENT DESCRIPTION: 


location of trap number 


Any address form valid for a data register; provides 
the trap number (0 through 63, decimal) of the trap to 
be disabled. A value of -l designates that all traps 
are to be disabled. The trap number must have been 
specified in an enable user trap (SENTRP) macro call. 


FUNCTION DESCRIPTION: 


This macro call disables the hardware trap vector specified 
by argument 1. All subsequent occurrences of the specified 
trap are handled by the system's default trap handling rou- 
tine until an enable user trap macro call is later issued 
for the trap. (Section 7 describes trap handling.) 


NOTES: 1. The trap number of the trap to be disabled, sup- 
plied by argument 1, is placed in $R2; if this 
argument is omitted, SR2 is assumed to contain 
the binary number of the trap to be disabled. 


2. On return, SR1 and S$R2 contain the following 
information: 


5-80 CBO08 


SR1 - Return status: 
O000 -— No error 
0342 - Illegal trap number 
0343 - A previously Signalled trap is 
still pending. 
SR2 - Trap number supplied in macro call 


Example: 


see the example given for "Connect Trap Handler." 
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DISSOCIATE FILE 


DISSOCIATE FILE 
Macro Call Name: SDSFIL 


Function Code: 10/15 
Equivalent Command: Dissociate Path (DISSOC) 


Dissociates a previously associated logical file number 


(LFN) from a pathname. This dissociation is typically done 
outside of program execution. 


FORMAT: 


[label] SDSFIL [parameter structure address] 


ARGUMENT DESCRIPTION: 
parameter structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 


below. The argument structure must contain the fol- 
lowing entry. 


logical file number 


A 2-byte logical file number (LFN) uSed to refer 
to the pathname; must be a binary number in the 
range 0 through 255. 


FUNCTION DESCRIPTION: 


This macro call breaks the logical connection between the 
specified LFN and its previously associated pathname (see 
the associate file macro call). It does not remove the file 
from the task group (see the remove file macro call). 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the argument structure. 
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2. On return, S$R1 contains one of the following 
Status codes: 


O0O00 - No error 
0205 - Illegal argument 
0206 - Unknown or illegal LFN 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In this example, the macro call identifies the same argument 
structure used in the associate file macro call described 
earlier (i.e., FILE A). The effect of the dissociate macro 
call is to remove the logical connection between the LFN and 
the pathname IDX01, as established by the associate file 
macro call. 


FILE A DC 5 LFNS5 
SDSFIL 'FTLE-A 
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ENABLE DEVICE 


ENABLE DEVICE (MOD 400 ONLY) 
Macro Call Name: SENDV 
Function Code: 02/04 
Equivalent Command: None 


set the resource control table (RCT) of the specified device 
to enabled status. 


FORMAT: 
[label] SENDV [location of LRN] 
ARGUMENT DESCRIPTION: 


location of LRN 


Any address form valid for a data register; provides 
the LRN of the device whose RCT is to be set to 
enabled status. The LRN must be a system LRN (defined 
at system building). 


FUNCTION DESCRIPTION: 


This call turns off the device disabled indicator (bit 10 of 
the R_FLGS entry) in the RCT of the specified device. SENDV 
can be used in synchronizing task operation with device 
availability. A task can issue a disable device on atten- 
tion macro call (SDSDV) to request notification of an inter- 
rupt. When the interrupt occurs, the device driver will set 
bit 10 (device disabled) and bit 8 (attention has occurred) 
of R_FLGS. When a ready interrupt is generated, the task 
can clear the disabled status by resetting bit 10 through 
the SENDV macro call. 


After clearing bit 8, using the reset device attention 
(SRDVAT) macro call, and waiting for the device ready inter- 
rupt to occur, a task can use the enable device (SENDV) and 
the reset device attention (SRDVAT) macro calls to clear 
bits 8 and 10 to initial states. 


5-84 CB08 


NOTES: 1. The LRN supplied by argument 1] is placed in $R2; 
if this argument is omitted, SR2 is assumed to 
contain the correct LRN. 


2. On return, SR1 and $R2 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 -—- No error 
0102 - Invalid LRN 


SR2 - LRN of device 


Example: 


In this example, the SENDV macro call is used to set the RCT 
of the device whose LRN is 15 to the enabled status. It is 


assumed that a ready interrupt has been generated for the 
device. 


ONDEVA SENDV =15 
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ENABLE USER TRAP 


ENABLE USER TRAP 
Macro Call Name: SENTRP 
Function Code: OA/01 
Equivalent Command: None 
Enable a specified user trap for the issuing task. 


FORMAT: 


[label] SENTRP [location of trap number] 


ARGUMENT DESCRIPTION: 
location of trap number 


Any address form valid for a data register; provides 
the trap number of the trap to be enabled. The trap 
number is a decimal value from 0 through 63, or a 
value of -l. A -1 value designates that all user 
traps are to be enabled. 


FUNCTION DESCRIPTION: 


This call causes a specific hardware trap vector whose 
number is derived from argument 1 to be enabled. All subse- 
quent occurrences of the specified trap cause control to be 
transferred to a previously established trap handling rou- 
tine for the task (See connect trap handler macro call). 


When the task group's general trap handling routine is 
entered, SR3 contains the trap number assigned to the event 
that caused the entry to the routine. $B3 contains the 
location of the trap save area. The j-mode bit in the I- 
register has been set off. All other registers are 
unchanged. An RTT (return from trap) instruction is exe- 
cuted to return from the task's trap handler. (See Section 
7 for more information about trap handling.) 
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( NOTES: 1. 


Example: 


The trap number of the trap to be enabled, sup- 
plied by argument 1, is placed in S$R2; if this 
argument is omitted, SR2 is assumed to contain 
the binary number of the trap to be enabled. 


On return, $R1 and $R2 contain the following 
information: 


SR1 - Return status; one of the following: 
0000 - No error 
0341 - Trap handler entry not connected 


0342 - Illegal trap number (requested trap 
not a user class trap). 


SR2 - Trap number supplied in macro call 


This macro call is required in order to enable a 
software simulated trap in a task that the user 
interrupts with the break key function, and for 
which a PI or UW break response is entered. 


See the example given for "Connect Trap Handler." 
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ERROR LOGGING, END 


ERROR LOGGING, END 

Macro Call Name: SELEND 
Function Code: 02/09 
Equivalent Command: None 


Terminate the error logging function for the named device 
and provide summary error information. 


FORMAT: 


[label] SELEND [location of device-name], 
[address of user's error logging table] 


ARGUMENT DESCRIPTION: 


location of device-name 


Any address form valid for a data register. Provides 
the address of the device-name for the peripheral 
(noncommunications) device for which the logging func-— 
tion is to be terminated. 


address of user's logging table 


Any address form valid for a data register. Provides 
the address of the previously generated 27-word user's 
error logging table. (See Table 5-1 in the discussion 
of error logging information exchange (SELEX) macro 
call.) 


FUNCTION DESCRIPTION: 


This call terminates the error logging function previously 
activated for this device. The system transfers logging 
information values from the system logging table into the 
user's logging table in memory (i.e., delivers to the user 
information (1) about the current status of the error log- 
ging table up to the time of the macro call, and (2) about 
the last error that occurred. (See Table 5-1.) 
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NOTES: 


When argument 1 is specified, the location of 
the device-name is placed in S$B2. If the argu- 
ment is omitted, the system assumes that S$B2 
contains a pointer to the device-name. | 


When argument 2 is specified, the address of the 
user's logging table is placed in $B4. When the 
argument is omitted, the system assumes that SB4 
contains a pointer to that table. 


The device name must have been specified (or 
defaulted) in a previously executed SELST macro 
call for that device. 


On return, SR1 contains one of the following 
status codes: 


0000 


Error logging terminated successfully. 


3B01 - Invalid argument (1 or 2). 


3B02 - Named device is nonexistent. 
3B05 - Logging function for this device is not 
active. 


3B08 - Illegal function code. 


3BOA - Device-name refers to a communications 
device. Macro call cannot be executed. 
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ERROR LOGGING 
INFORMATION, EXCHANGE 


ERROR LOGGING INFORMATION, EXCHANGE 
Macro Call Name: SELEX 
Function Code: 02/07 


Equivalent Command: None 


Verifies, then saves the values in the user's error logging 
table; transfers current logging values from system's error 
logging table to user's error logging table; moves the saved 


user-Ssupplied error logging values into the system's logging 
table. 


FORMAT : 


[label] SELEX flocation of device-name], 
[address of user's error logging table] 


ARGUMENT DESCRIPTION: 


location of device-name 


Any address form valid for a data register. Provides 
the address of the device-name (previously coded in 
SELST macro call for this device) for the device whose 
error logging values are to be exchanged. 


address of user's logging table 


Any address form valid for a data register; provides 
the address of the previously generated 27-word user's 
error logging table. Table 5-1 below defines the 
user's error logging table, which the user must build 


and initialize before issuing any error logging macro 
call. 
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Table 5-1. User-Generated Table for Error Logging Macro Calls 


Word(s) Value (Signed Binary) Function 


User-Specified in SELST and SELEX Macro Calls 


1 and 2 | Two-word integer 2 0; Counter for number of I/0 
normally initialized to 0. |orders. 
i: One-word integer > 0; Counter for number of device 
normally initialized to 0. | read/write errors. 


One-word integer from 0 Error threshold ratio. A 


through 1000, represented ratio of DC 10 (i.e., 1%) is 
as a fraction in thou- Suggested for magnetic tape. 
sandths; i.e., DC 500 

means .500. 


One-word integer > 0. Minimum number of I/O orders 
processed before error 
threshold ratio is checked. 


E 


Values Returned by SELGT, SELEX, SELEND Macro Calls 


History counter. Total number of errors up to 
time information returned in 
this macro call. 


History counter. Error threshold ratio when 
information is returned in 
this macro call. 


Ore History value. Internal date/time of macro 
call return. 


Left byte. LRN for this device. 


~ 
\O 


Right byte. Device type. 


20-22 


Internal date/time that last 
error occurred. 


last error occurred. 
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FUNCTION DESCRIPTION: 


This call causes the system to deliver to the user informa- 
tion about (1) the current status of the system's logging 
table up to the time of the macro call, and (2) about the 
last error that occurred, as indicated by words 7 through 27 
in Table 5-1. The system (1) checks the values of the 
user's error logging table for errors, and if they are cor- 
rect, saves those values; (2) executes a SELGT macro call to 
move current values from the system's logging table to the 
user's logging table; and (3) moves and stores in the sys- 
tem's logging table the new logging values verified and 
saved from the user's logging table, thus replacing the 
previous values in the system's logging table. History 
counters in the system's logging table are reset to 0. 


NOTES: 1. When argument 1 is specified, the location of 
the device name is placed in $B2. If the argu- 
ment is omitted, the system assumes that S$B2 
contains a pointer to the device name. 


2. When argument 2 is specified, the address of the 
user's logging table is placed in $B4. When the 
argument is omitted, the system assumes that SB4 
contains a pointer to that table. 

3. The device name must have been specified (or 
defaulted) in a previously executed SELST macro 
call for that device. 


4. On return, $R1 contains one of the following 
Status codes: 


0000 - Error logging information successfully 
exchanged. 


3B01 - Invalid argument (1 or 2). 
3B02 - Named device is nonexistent. 


3B03 - Illegal value specified for minimum 
number of I/O orders. 


3B05 - Logging function for this device is not 
active. 


3B06 - Illegal value specified for threshold. 


3B07 - Illegal initial value for I/O order 
counter or device error counter. 


3B08 - Illegal function code. 
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3B0A 


—- Device name refers to communications 
device; macro call cannot be executed. 
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ERROR LOGGING 
INFORMATION, GET 


ERROR LOGGING INFORMATION, GET 
Macro Call Name: SELGT 
Function Code: 02/08 
Equivalent Command: None 


Retrieve current logging information values, for the named 
device, from the system's error logging table; place them in 
the user's error logging table. / 


FORMAT : 


[label] SELGT [location of device-name], 
[address of user's error logging table] 


ARGUMENT DESCRIPTION: 
location of device-name 


Any address form valid for a data register. Provides 
the address of the device-name (previously coded in a 
SELST macro call for this device) for the device whose 
error logging error information is to be transferred. 


address of user's logging table 


Any address form valid for a data register. Provides 
the address of the previously generated 27-word user's 
error logging table (see Table 5-1 in the discussion 
of the-error logging information exchange (SELEX) 
macro call.) 


FUNCTION DESCRIPTION: 


This call transfers current error logging information 
values, for the named device, from the system's error log- 
ging table to the user's error logging table in memory. 
Error logging must have been previously activated for the 
device. Only those items in the system's logging table, 
that have corresponding entries in the user's logging table, 
are transferred. 
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Mie, 


NOTES: 


When argument 1 is specified, the location of 
the device-name is placed in SB2. If the argu- 
ment is omitted, the system assumes that S$B2 
contains a pointer to the device-name. 


When argument 2 is specified, the address of the 
user's logging table is placed in $B4. When the 
argument is omitted, the system assumes that $B4 
contains a pointer to that table. 

The device-name must have been specified (or 
defaulted) in a previously executed SELST macro 
call for that device. 


On return, $R1 contains one of the following 
Status codes: 


0000 - Error logging values successfully 
transferred. 


3B01 - Invalid argument (1 or 2). 
3B02 - Named device is nonexistent. 


3B05 - Logging function for this device is not 
active. 


3B08 - Illegal function code. 


3BOA - Device-name refers to a communications 
device; macro call cannot be executed. 
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ERROR LOGGING, START 


ERROR LOGGING, START 
Macro Call Name: SELST 
Function Code: 02/05 
Equivalent. Command: None 


Activate error logging for the named device. 


FORMAT : 


[label] SELST [location of device-name], 
[address of user's error logging table] 


ARGUMENT DESCRIPTION: 


location of device-name 


Any address form valid for a data register. Provides 
the address of the device-name (designated at system 
building) for the peripheral (noncommunications) 


device to be monitored. Device name can have up to 12 
ASCII characters. 


address of user's logging table 


Any address form valid for a data register. Provides 
the address of the user's error logging table, which 
must have been previously generated. (See Table 5-1 
in the discussion of the error logging information 
exchange (SELEX) macro call.) This macro call 
requires only the first six words of the user's error 
logging structure. 


FUNCTION DESCRIPTION: 


This macro call starts error logging for the named device, 
and maintains error logging information in memory. The call 
(1) allocates a block of system memory for the system's log- 
ging table; (2) checks parameters in the first six words of 
the user's logging table and stores the values in the sys- 
tem's logging table in memory; and (3) stores in the 


5-96 CBO08 


BAe, 


device's RCT a pointer to the system's logging memory area, 
which activates the logging function. Before this macro 
call is issued, the user must build and initialize at least 
a six-word error logging table, as defined in Table 5-l. 
Whenever an I/O order is issued, the system increments the 
I/O counter (words 1 and 2 in Table 5-1). When there is a 
device error, the system increments the device error counter 
(word 3). When the specified number of I/O orders (word 6) 
is processed, the system checks the error threshold ratio 
(word 5) and if the value is exceeded, sends a message to 
the operator and resets the system's error logging table for 
this device. 


The logging table is reset under any of the following 
conditions: 


1. Designated error threshold ratio exceeded. 


2. Either the I/O order counter (words 1 and 2) or device 
error counter (word 3) overflowed. 


oe SELEX macro call is executed. 


When 1 or 2 occurs, the current value of the I/O order and 
device error counters are added to the history values in the 
system's error logging table. (These history values may be 
later delivered to corresponding history areas in the user's 
logging table (see Table 5-1)). If there is overflow in the 
addition, these counters are reset to 0, but the error 
threshold (word 4) and I/O order minimum (word 5) values are 
retained. When 3 occurs (SELEX executed), the items in the 
System logging table are reinitialized from the new values 
Supplied in the user's logging table. 


NOTES: 1. When argument 1 is specified, the location of 
the device-name is placed in $B2. If the argu- 
ment iS omitted, the system assumes that S$B2 
contains a pointer to the device-name.. 


2. When argument 2 is specified, the address of the 
user's logging table is placed in $B4. When the 
argument is omitted, the system assumes that S$B4 
contains a pointer to that table. 


3. The device-name must be that of a noncommunica- 
tions peripheral device, 1.e., cannot be con- 
nected to an MLCP or DLCP. 


4. On return, $R1 contains one of the following 
Status codes: 


0000 - Error logging activated successfully. 
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3B 01 


3B02 


3B03 


3B06 


3B07 


3B08 


3B 09 


3B0A 


Invalid argument (1 or 2). 
Named device is nonexistent. 


Illegal value specified for minimum 


number of I/O orders. 


Illegal value specified for threshold. 


Illegal initial value for I/O order 
counter or device error counter. 


Tllegal function code. 


Insufficient system memory for logging 
table. 


Device-name refers to communications 
device; logging cannot be activated. 


The user can move the latest error logging. 
information values from the system logging table 
to the user's logging table with a SELGT, SELEX, 
or SELEND macro call. | 
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ERROR OUT 


ERROR OUT 
Macro Call Name: SEROUT 
Function Code: 08/03 


Equivalent Command: None 


Write the next record to the error-out file for the task 
group of the issuing task. 


FORMAT: 
[label] SEROUT [location of record area address], 


[location of record size], 
[byte offset from beginning of record area] 


ARGUMENT DESCRIPTION: 
location of record area address 


Any address form valid for an address register; pro- 
vides the address of a record area containing the 
record to be written to the error-out file. The first 
byte of the record must be a slew byte (print file 


form control byte; see "Printer Driver" in Section 6). 
The record text begins in the second byte. 


location of record size 


Any address form valid for a data register; provides 
the size (in bytes) of the record whose address is 


given in argument 1. The output size value must 
include the slew byte. 
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byte offset of beginning of record area 


Any address form valid for a data register; provides 
the byte offset of the beginning of the record area 
(from the address provided in argument 1). If argu- 
ment 3 is L, the record begins in the left byte of the 
address specified in argument 1; if argument 3 is R, 
the record area begins in the right byte of this 
address. Any other value for argument 3 is taken to 
be the location of the byte offset. If argument 3 is 
omitted, the record area is assumed to begin at the 
left byte of the address specified in argument l. 


FUNCTION DESCRIPTION: 


This call allows a task to write the next record (an error 
message record) to the current error-out file. The error- 
out file is the same as the initial user-out file defined in 
the request group (SRQGRP) macro call, and cannot be changed 
during execution of the request. 


NOTES: 1. The address of the record to be written, sup- 
plied by argument 1, is placed in $B4; if this 
argument is omitted, $B4 is assumed to contain 
the address of the output record. 


2. The output record size, supplied by argument 2, 
is placed in S$R6; if this argument is omitted, 
SR6 is assumed to contain the size of the 
record. 


3. If argument 3 is L, $R7 is set to zero to desig- 
nate that the record area begins in the left 
byte of the specified address. If argument 3 is 
R, SR7 is set to one to designate that the 
record area begins in the right byte of the 
Specified address. Any other value is assumed 
to be the location of the byte offset to be 
used, and is placed in SR7. If argument 3 is 
omitted, the record area is assumed to begin in 
the left byte of the specified address, and SR7 
is set to Zero. 


4, On return, SR1, SR6, and $B4 contain the fol- 
lowing information: 


SR1 - Return status; one of the following: 


0000 -— No error 
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( All data management write-next-record 
error codes may also be returned. See the 
System Messages manual. 


SR6 — Residual range (number of bytes not 
transferred from record area). 


SB4 - Address of record area containing output 
record. 


Example: 

In this example, the issuing task is to write an error mes- 
sage record on the error-out file. The record length is 12 
bytes (including the slew byte). The output record is 


located at the record area address RECAD. The record area 
begins at the leftmost byte of the indicated address. 


OUTRB SEROUT !'RECAD,=12 


RECAD TEXT "AFIELD ERROR' 
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EXPAND PATHNAME 


EXPAND PATHNAME 
Macro Call Name: SXPATH 
Function Code: 10/D0 
Equivalent Command: None 
Develop a full pathname from a relative pathname. 
FORMAT: 
[label] SXPATH fargument structure address] 
ARGUMENT DESCRIPTION: 
argument structure address 
Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 
input pathname pointer 
A 4-byte address, which may be any address form 
valid for an address register; points to a 
relative pathname (which must end with an ASCII 
Space character) to be expanded. 
output pathname pointer 
A 4-byte address, which may be any address form 
valid for an address register; identifies a 58- 
byte field into which the absolute (i.e., 
expanded) pathname is placed by the system. 


pathname base 


A 2-byte binary value that specifies the basis 
on which to expand the relative path, as 
follows: 
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0000 - Working directory 
0001 - System library-l 
0002 -—- System library-2 


FUNCTION DESCRIPTION: 


This macro call will expand any relative pathname, regard- 
less of the format in which it is supplied, into an absolute 
pathname. It is possible that the resulting pathname will 
point to a nonexistent file. The expanded pathname cannot 
exceed 58 characters. 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the argument structure. 


2. On return, SR1 contains one of the following 
status codes: 


0000 - Successful completion 

0201 - Illegal pathname 

0205 - Illegal argument 

0222 - Pathname cannot be expanded, no working 


directory 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In this example, the pathname of the working directory is 
VOL6 SUB1 SUB2 SUB3 SUB4, and you want to develop a fully 
expanded absolute pathname from the relative pathname ADF. 

In the macro call, you must identify the relative pathname 

( ADF) and the basis (working directory) on which the 
absolute pathname is to be developed, as well aS an area 
into which the system can place the fully expanded absolute 
pathname. The main memory area is defined as follows: 


X NAME RESV 29 
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The argument structure is built as follows: 


XPND 1 DC <RELDPH 
_ RESV 2-SAF 
DC <X_NAME 
 RESV 2-SAF 
DC 0 


The relative pathname is defined as follows: 
RELPTH DC '<<ADFA' 


The fully expanded pathname \YOL6>SUB1>SUB2>ADF is developed 
as a result of the following macro call. 


SXPATH  !XPND_1 
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EXTERNAL DATE/TIME, CONVERT TO 


EXTERNAL DATE/TIME, CONVERT TO 


Macro Call Name: SEXTDT 
Function Code: 05/04 
Equivalent Command: Time (TIME) 


Convert an internal format date/time value to an external 
format date/time value. 


FORMAT: 


[label] SEXTDT [location of address of internal date/time], 
[location of address receiving field], 
[location of size of receiving field] 


ARGUMENT DESCRIPTION: 
location of address of internal date/time 


Any address form valid for an address register; pro- 
vides the address of the 3-word field containing the 
internal date/time value to be converted. This value 
must be in the format returned by the get date/time 
macro call (SGDTM). 


location of address of receiving field 


Any address form valid for an address register; pro- 
vides the address of a field in the issuing task that 
is to receive the external format date/time value. 


location of size of receiving field 


Any address form valid for a data register; provides 
the size of the receiving field identified by argument 
2. The field size must be less than or equal to 22 
bytes. If this argument is omitted, the size is set 
to 20 bytes (the date/time value is resolved to a 
tenth of a second). 
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FUNCTION DESCRIPTION: 


This call converts an internal date/time value (in the 
format supplied by the get date/time macro call) to an 
external date/time format. The date/time value appears in 
the receiving field as a character string having the format: 


Word | Contents 


yy (Two ASCII numeric characters) 
yy (Two ASCII numeric characters) 
/m (Two ASCII characters) 
m/ (Two ASCII characters) 
dd (Two ASCII numeric characters) 
(Two ASCII characters) 
hm (Two ASCII numeric characters) 
m: (Two ASCII characters) 
ss (Two ASCII numeric characters) 
-t (Two ASCII characters) 


Do ON AUN BW YF © 
— 


1 tt (Two ASCII numeric characters) 
yyyy - Year mm — Minute 
mm —- Month Ss - Seconds 
dd - Day ttt - Tenths, hundredths, 
hh - Hour thousandths of seconds 


The size of the receiving field cannot be such that the 
Field terminates with a punctuation character (/, :, or .). 
Thus argument 3 cannot specify a size of 5, 8, 16, or 19 
bytes. 


NOTES: 1. The internal date/time value whose address was 
supplied by argument 1 is loaded into $R2, SR6, 
and SR7. If argument 1 is omitted, or is =SR7, 
it is assumed that S$R2, S$R6, and SR7 contain the 
value to be converted. 


2. The address of the receiving field supplied by 
argument 2 is placed in $B4; if this argument is 
omitted, $B4 is assumed to contain the correct 
address. 


3. The size of the receiving field supplied by 
argument 3 is placed in SR5. If this argument 
is given as =SR5, S$R5 is assumed to contain the 
correct size. If this argument is omitted, SR5 
is set to 20 bytes (tenth of a second 
resolution). 
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4, On return, S$R1, SR2, SR6, S$R7 and $B4 contain 
the following information: 


SR1 - Return status; one of the following: 


OQ00 — No error 


0402 - Invalid (negative) receiving field 
length 

O40A ~- Invalid receiving field address 

0817 - Memory access violation 


SR2, SR6, SR7 - Internal date/time value 
supplied 


SB4 - Address of receiving field 
Example: 


see the example given for the get date/time macro call. 
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EXTERNAL TIME, CONVERT TO 


EXTERNAL TI 


Macro Call 


Function Co 


ME, CONVERT TO 
Name: SEXTIM 


de: 05/05 


Equivalent Command: None 
Convert an internal format date/time value to an external 
format time value. 
FORMAT : 
[label] SEXTIM [location of address of internal date/timel, 


ARGUME 


locati 


locati 


locati 


[location of address of receiving field], 
[location of length of receiving field] 


NT DESCRIPTION: 
on of address of internal date/time 


Any address form valid for an address register; pro- 
vides the address of a 3-word field containing the 
internal date/time value to be converted. This value 
must be in the format returned by the get date/time 
macro call. 


on of address of receiving field 


Any address form valid for an address register; pro- 
vides the address of a field in the issuing task that 
is to receive the external format time value. 


on of length of receiving field 


Any address form valid for a data register, provides 
the size of the receiving field identified by argument 
2. The field size must be less than or equal to ll 
bytes. If this argument is omitted, the size is set 
to 9 bytes (the time is resolved to a tenth of a 
second). 
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FUNCTION DESCRIPTION: 


This call converts an internal date/time value (in the 
format supplied by the get date/time macro call) to an 
external time format. The time value appears in the 
receiving field as a character string having the format 
hhmm:ss.ttt (see below). 


Word Contents 
0 hh (two ASCII numeric characters) 
1 mm (two ASCII numeric characters) 
2 :s (two ASCII characters) 
3 S. (two ASCII characters) 
4 tt (two ASCII numeric characters) 
5 a (two ASCII characters) 
hh -— hours ss -— Seconds 
mm — minutes ttt -—- tenths, hundredths, 


thousandths of seconds 


The size of the receiving field cannot be such that the 
field terminates with a punctuation character (: or .). 
Thus, the third argument cannot be 5 or 8. 


NOTES: 1. The internal date/time value whose address is 
supplied by argument 1 is loaded into SR2, SR6, 
and SR7. If argument 1 is omitted, or is =SR7, 
it is assumed that $R2, S$R6, and SR7 contain the 
internal value to be converted. 


EB, 


2. The address of the receiving field supplied by 
argument 2 is placed in $B4; if this argument is 
omitted, SB4 is assumed to contain the correct 
address. 


3. The size of the receiving field supplied by 
argument 3 is placed in $R5. If argument 3 is 
=SR5, it is assumed that $R5 contains the cor- 
rect size. If this argument is omitted, S$R5 is 
set to 9 bytes (tenth of a second resolution). 


4. On return, SR1, $R2, $R6, S$R7, and $B4 contain 
the following information: 


SR1 - Return status; one of the fololowing: 
OCOO0 -— No error 


0402 - Invalid (negative) receiving field 
length 
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O40A - Invalid receiving field address 
0817 - Memory access violation 


SR2, SR6, SR7 - Internal date/time value 
supplied 


SB4 - Address of receiving field 
Example: 


In this example, the SGDTM macro call is used to get the 
current date/time, in internal format, leaving it in reg- 
isters SR2, S$R6, and $R7. The SEXTIM macro call is then 
used to format this internal date/time value into a dis- 
Playable format with a resolution to milliseconds. A mes- 
Sage containing the external format date/time is then 
written on the user-out file. 


* 


* GET THE CURRENT DATE/TIME. 
* 


SGDTM 

* 

* FORMAT IT FOR DISPLAY. 

* 

SEXTIM ,!P1_ TIM,=11 

* 

* OUTPUT THE MESSAGE. 

* | 

SUSOUT !Pl1 MSG,=P1_MLN 

Pl MSG = TEXT 'APHASE 1 FINISHED ATA' 
Pl TIM TEXT 'HHMM:SS.TTT! 
Pl MLN EQU 2*($-P1l MSG) 
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FILE INFORMATION BLOCK 


FILE INFORMATION BLOCK 


Macro Call Name: SFIB 
Function Code: None 
Equivalent Command: None 


Depending on the arguments supplied in the call, does one of 
the following: 


o Builds a 16-word file information block (FIB) containing 
default values for the words. 


o Generates instructions to alter the partial contents of 
an existing FIB. 


o Calls and expands the STFIB macro call to provide labels 
for the FIB entries. 


FORMAT : 


[label] SFIB  farguments] 
ARGUMENT DESCRIPTION: 
There are three types of arguments for this macro call: 
o Keyword only 
o Keyword with expression 


o Keyword with option 


The keyword RESV generates a data structure. The SFIB macro 
without the keyword RESV generates executable code to modify 
an existing data structure. 


When the call is coded with only the keyword RESV, a 16-word 


FIB containing default values is built (with tags for the 
entries). The entries have the following values: 


5-111 CBO8 


DC 0 
DC B'0110010010000000 ' 


DC 0,0 

DC 80 

DC 80 

DC 0 

DC Z'FFFF ! 
DC 0 

DC 0,0 

DC Z'0104' 
DC 0,0 

DC 0,0. 


The default values generated for this FIB allow access to a 
file for reading and writing, and allow record access by 
both primary and relative keys. The default input and 
output record lengths are 80 characters; the default key 
format for input records is primary; key length is 4 bytes. 


When the keyword RESV is used with other arguments, it 
preserves all entries in the generated FIB that are not 
Specifically changed by the other arguments. 


Arguments coded as keyword=expression apply to the words of 
the file information block. These arguments can be coded. 
in any order. If a new FIB is to be built and an argument 
is omitted, the default value (described above) for that 
word is used. If an existing FIB is to be modified and an 
argument is omitted, the existing value for that word is 
used. The diagram below shows the keywords and possible 
expression values, but does not necessarily correspond to 
the FIB physical structure. For more detailed information, 
see Tables 3-1 and 3-2. 


A value from 0 through 255 specifying the logical 
file number by which the file is referenced; or -1; 
or A'AA' (two ASCII space characters). 


A value specifying the desired program view word 


(i.e., user visibility), as follows: 
Bits . Meaning 
@) Access level: 


O - Access via data management 
1 - Access via storage management 
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Ke ywo rd 


PVW= 
(cont) 


ExpresSion 
Meaning 


Process rules: 


1000 SRDREC or SRDBLK macro calls permitted 
0100 - SWRREC or SWRBLK macro calls permitted 


0010 


SRWREC macro call permitted 
0001 - SDLREC macro call permitted 


nnnn - Any combination of the binary settings 
to allow the deSired macro calls 


Key type: 

10000 - Primary keys allowed 
00010 - Relative keys allowed 
00001 - Simple keys allowed 


nOOnn — Any combination of binary settings to 
allow the desired keys 


NOTE: Bits 10-14 are data management specific 
and can be set before the file is opened. 


Record class: 


O - Fixed- and variable-length records allowed 
1 - Only fixed-length records allowed 


Record visibility: 


O - Deleted records are not visible during a 
read next record operation 


1 - Deleted records are visible 


Key storage area alignment: 


| O - Area begins at even-byte boundary 
1 


- Area begins at odd-byte boundary 
Record storage area/buffer alignment: 
0 - Begins at even-byte boundary 


1 - Begins at odd-byte boundary 
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Expression 


Bits Meaning 


14 Transcription mode: 
0 - ASCII mode 
1 - Binary transcription mode 
15 SynchronousS/asynchronous indicator: 


0 - SRDBLK or SWRBLK macro calls to be 
executed synchronously 


1 - These calls to be executed asynchronously 
URP= Address of start of user record area (data manage- 
ment) or start of buffer area (storage management) 


a IRL= Maximum size of input record for data management 
operations 
Actual size of output record 


% 
IKP= Address of user key area in which key value is 
stored 
IKF= Type of key: 
00 —- None specified | 
O01 - Primary or relative (see bits 5-9 of PVW) 
02 - Simple 
IKL= 
the RESV keyword, the value specified for IKL must 
be a l-byte hexadecimal number (e.g., OA, 01, etc.). 
BFS= Value specifying size of data transfer (block size) 
for storage management operations. 
BNL= Left half of block number; an integer relative to 
the beginning of the file (storage management) 


| BNR= Right half of block number; an integer relative to 
the beginning of the file (storage management) 
ADR= Address of FIB to be modified. Not used when 
building new FIBs. 
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Value specifying the length of the user key area 
(IKP). A maximum of 256 ASCII characters is allowed 
for primary keys. (Simple and relative keys are 
always assumed to be four bytes.) When used with 


Arguments coded as keyword=option apply only to the program 
view word of the FIB. Options can be given in any order; 
more than one option value can be specified per argument. 
Bits in the program view word that are not explicitly given 
a value through an option selection retain their previous 
setting. The diagram below shows the keywords and possible 
values for the expressions. See Table 3-2 for more detailed 
information. 


Keyword |Option Meaning 
LOCOS EN Mee Tee Een 


SFN= File can be read by S$RDREC or SRDBLK macro 
calls 


WR File can be written by SWRREC or SWRBLK 
macro calls 


RW File can be rewritten by SRWREC macro call 


DL File can be deleted by $DLREC macro call 


RD File cannot be read by SRDREC or SRDBLK 
macro calls 


WR File cannot be written by SWRREC or SWRBLK 
macro calls 


RW File cannot be rewritten by SRWREC macro 
call 


DL File cannot be deleted by SDLREC macro call 
P Primary keys allowed 


R Relative keys allowed 


S Simple keys allowed 
RKA= P Primary keys not allowed 
R Relative keys not allowed 
S Simple keys not allowed 
SRA= FL | Only fixed-length records allowed 
DV Deleted records are visible 
RRA= FL Fixed- and variable-length records allowed 


DV Deleted records are not visible 
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Meaning 


SSM= Binary transcription mode used for data 


transfer 


SRDBLK or SWRBLK macro calls executed 
asynchronously 


File accessed via storage management 


ts 
ASCII mode used for data transfer 
SRDBLK or SWRBLK macro calls executed 
synchronously 

| File accessed via data management 


Key storage area begins at odd-byte boundary 


Record storage area begins at odd-byte 
boundary 


Key storage area begins at even-byte 
boundary 


Record storage area begins at even-byte 
boundary 


If no arguments are coded, the STFIB macro call is expanded. 
FUNCTION DESCRIPTION: 


This call (1) generates a 16-word FIB, or (2) alters the 
contents of an existing FIB, and (3) calls and expands the 
STFIB offsets macro call. 


A FIB must exist for a file if that file is to be operated 
upon by one of the following macro calls: 


Open file (SOPFIL) 

Close file (SCLFIL) 

Test file (STIFIL, STOFIL) 
Read record (SRDREC) 

Write record (SWRREC) 
Rewrite record (SRWREC) 
Delete record (S$DLREC) 
Read block (SRDBLK) 

Write block (SWRBLK) 

Wait block (SWTBLK) 


Oo00O0 00 0000 
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( If an existing FIB is to be modified and the argument ADR= 
| is not entered, $B4 is assumed to point to the FIB to be 
modified. 7 


Registers S$R7 and SB5 are altered when an existing FIB is 
modified. 


Macro global value GX is used to control expansion of the 
STFIB macro call. 


When you use the SFIB macro call to alter an existing FIB, 
arguments that use an address follow the convention in which 
addresses preceded by the ! character cause an LAB instruc-— 
tion to be generated, and addresses not preceded by the ! 
Character cause an LDB instruction to be generated. When 
you supply values for arguments coded as keyword=expression 
(IRL=, ORL=, etc.), the address of the value is distin- 
guished by a preceding character. No special character is 
needed to indicate that the string following the = character 
is a value. The second example given below uses both values 
and addresses (IFL=128 and ORL= LENGTH). 


The expressions specified with each argument must be in a 
form Suitable for the DC statement. IKF and IKL must 
specify a l-byte hexadecimal number. 


Example 1: 


In this example, the STFIB macro call is expanded. 
SFIB 
Example 2: 
In this example, an existing FIB is modified. This example 
assumes that the S$B4 register was previously loaded with the 
address of the FIB to be modified. 
SFIB URP=!REC1,RFN=WR, SRA=FL, ODD=RC, IRL=128, LFN=<GET PRM 


Execution of the macro call generates the following set of 
instructions: 


LAB SB5,REC1 

STB SB5,$B4.F _URP 

LBF SB4,F PROV,B'0010000000000000'! 
LBT SB4,F PROV,B'0000000000100100' 
LDR SR7,=128 

STR SR7,$B4.F_ IRL 

LDR SR7,GETPRM 

STR SR7,SB4.F_LFN 
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Example 3: 


This example generates a FIB so that the file can be 
accessed for reading, writing, rewriting, and deleting 
records by either primary or relative keys. The rewrite and 
delete bits (bits 3 and 4) of the program view word are 
altered from the original values (provided by the RESV 
parameter) by means of the SFN=RWDL argument. 


EXTFIB SF IB LFN=3, IKF=02, RESV, SFN=RWDL, SKA=PR, IKP=<KEY 


This macro call generates the following FIB: 


EXTFIB DC 3 
DC B'0111110010000000' 
DC 0,0 
DC 80 
DC 20 
DC 0 
DC Z'FPFF! 
DC 0 
DC <KEY 
RESV 2-SAF 
DC Z'0204'! 
DC 0,0 
DC 0,0 


Example 4: 


In this example, a 16-word FIB is generated with default 
values for all words. 


EXTFIB SF IB RESV 


The following FIB is generated: 


EXTFIB DC 0 
DC B'0110010010000000 ' 
DC 0,0 
DC 80 
DC 80 
DC 0 
DC Z‘'FFFFS 
DC 0 
DC 0,0 
DC Z‘'0104'! 
DC 0,0 
DC 0,0 
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FILE INFORMATION BLOCK OFFSETS 


FILE INFORMATION BLOCK OFFSETS 

Macro Call Name: STFIB 

Associated Macro Calls: 
SOPFIL, SCLFIL, STIFIL, STOFIL, *K 
SRDREC, SWRREC, SRWREC, SDLREC, SRDBLK, 
SWRBLK, SWTBLK 

Generated Offsets Tags: 


Corresponding 


Offsets 

Tag (in Words) _ Entry Name 
F LFN 0 Logical file number (LFN) 
F PROV +] Progam view 
F URP +2 User record pointerl 
F IRL +4 Input record lengthl 
F ORL +5 Output record lengthl 
F ORT +8 Reservedl * 
F IKP +9 Input key pointerl 
F IKF +11 Input key format (first byte) l 
F IKL +11 Input key length (second byte) 1 
FORA +12 Output record addressl 
F ORA1 F_ORA(+12) (left half of F_ORA)1 
F ORA2 F ORA+1 (+13) (right half of F ORA)I1l 
F UBP +2 User buffer pointer2 
F BFSZ +4 Buffer size2 
F BKSZ +5 Block size2 
F BKNO +6 Block number2 


(left half of F BKNO) 


F BKNOl F BNKO(+6) = 
(right half of F BKNO) 


F_BKNO2 F BKNO+1 (+7) 


Size of structure (in words); 


F SZ +16 
not a field in the block 


TSpecific to SRDREC, SWRREC, SRWREC, and SDLREC macro calls. 


2Specific to S$RDBLK, and SWRBLK macro calls. 
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In addition to the offsets tags listed above, the following 
program view (F PROV tag, above) masks are defined: 


Tag 


MF_OPS 
MF RDA 


MF WRA 


MF RWA 
MF DLA 
MF PKA 
MF CKA 
MF 2KA 
MF RKA 
MF SKA 
MF FRA 
MF DLV 
MF KOD 
MF ROD 


MF BOD 
MF_BTM 


MF AIO 


Mask 


Z"8000 ' 
Z*'4000! 
Z‘'2000' 
Z‘'1000! 
Z*'0O800 ! 
Z'0400! 
Z'O200' 
Z‘'0100! 
Z*'OO80 ' 
Z'0040' 
Z*'0020' 
Z‘OO10' 
Z‘'0008 ! 
Z'0O004' 


Z'O0C04' 
Z'O002' 


Z'OQOO1' 


Meaning 


Open for storage management 

Read operations allowed 

Write operations allowed 

Rewrite operations allowed 

Delete operations allowed 

Access via primary key 

Reserved 

Reserved 

Access via relative key 

Access via Simple key 

Fixed length records allowed 

Deleted records visible to program 

Key area Starts an odd-byte boundary 
Record area starts at odd-byte boundary 
(data management specific) 

Buffer area starts at odd-byte boundary 
(storage management specific) 

Data transferred in binary 
transcription mode 

Next block function is asynchronous 
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GET DATE/TIME 


GET DATE/TIME 

Macro Call Name: SGDTM 
Function Code: 05/06 
Equivalent Command: None 


Supply the requesting task with the current internal date/ 
time value maintained by the system. 


FORMAT: 


[label] SGDTM [location of address of receiving field] 
ARGUMENT DESCRIPTION: 
location of address of receiving field 


Any address form valid for an address register; pro- 
vides the address of a 3-word field in the issuing 


task that is to receive the current internal date/time 
value. 


FUNCTION DESCRIPTION: 


This macro call returns to the issuing task the current 3- 
word internal date/time value. The leftmost word contains 
the most significant 16 bits; the rightmost word contains 
the least significant 16 bits. The value Supplied is a 
binary count of the milliseconds since 1] January 1901 at 
00:00:00.000 hours. 


NOTES: 1. The internal date/time value is returned in SR2, 
SR6, and $R7 and stored in the receiving field 
Specified by argument 1. If argument 1 is 
omitted, or is =SR7, the value is returned only 
in $R2, SR6, and SR7. 
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2. On return, SR1, $R2, SR6, and SR7 contain the 
following information: 


SR1 - Return status; one of the following: 


0000 - No error 
O40A - Invalid address for receiving field 


SR2, SR6, and SR7 —- Current 3-word internal 
date/time value. S$R2 contains the most 
significant 16 bits and SR7 the least 
Significant 16 bits. 


Example: 


In this example the SGDTM macro call is used to get the 
Starting date/time, in internal format, of a process and 
Store it in the field ST TIM. The convert to external date/ 
time macro call (SEXTDT) is then used to format this 
internal clock value, contained in registers $R2, SR6, and 
SR7, into a displayable date/time format with resolution to 
a tenth of a second. A startup message containing the 
external format date/time is then written on the user-out 
file. Later, the get date/time macro call is used again to 
get the finishing date/time of the process without storing 
it in memory. The low order two words of the starting date/ 
time are then subtracted from the corresponding words of the 
Finishing date/time, leaving the elapsed time (in milli- 
seconds) in $R6 and $R7. The subtraction is performed 
assuming a central processor that does not have the subtract 
integer double instruction. The high order word of the 
Starting and finishing date/time values is ignored with the 
assumption that the elapsed time is less than 2°%' milli- 
Seconds (about 24.855 days). 


* 


= GET THE STARTING TIME. 
x 


SGDTM !ST_TIM 


* 
* FORMAT IT FOR DISPLAY. 
* 

SEXTDT  ,!GO_TIM,20 
* 
* 


OUTPUT THE START UP MESSAGE. 


SUSOUT !GO MSG,=GO MLN 
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pte ae! 


% 


+ 


ST TIM 
GO_MSG 
GO TIM 
GO” MLN 


BEGIN PROCESSING. 


GET THE FINISHING TIME. 


SGDTM 


CALCULATE THE ELAPSED TIME, 


SUB 
BCT 
ADV 
SUB 


RESV 
TEXT 
TEXT 
FE; QU 


$R7,ST_TIM+2 

>S+2 

SR6,-1 

SR6,ST_ TIM+1 

3,0 

'APROGX STARTED ATA! 


'YYYY/MM/DD HHMM:SS.T' 
2*($-GO_MSG) 
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GET FILE - 


GET FILE 

Macro Call Name: SGTFIL 

Function Code: 10/20 

Equivalent Command: Get File (GET) 


Locate and reserve a file (tape or disk file, disk direc- 
tory, card reader, printer, or terminal device) for pro- 
cessing with the specified access rights. You identify the 
file by supplying either a logical file number (LFN) or a 
pathname. If you supply both an LFN and a pathname, the 
file is reserved and is assigned to the LFN. Subsequent 
macro calls (open file, read record, etc.) can then be 
directed to the file through this LFN. If the file is tape- 
resident, the get file macro call supplies the necessary 
tape definition arguments. This function is normally done 
outside program execution, to assign the LFN to a file that “he 
is not known until execution time. 


FORMAT : 

[label] SGTFIL [argument structure address] 
ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register, pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. The size of each 
entry, whose descriptions follow this list, is as 
follows: 
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Size 


Argument Structure Entry (in bytes) 


logi 


pointer pathname 
lock/concurrency control 


moun 
tape 


tape logical record size 
number of buffers 


tape 
tape 
tape 
tape 
tape 
tape 


logica 


pointe 


lock/c 


cal file number 


t option 
block size 


File sequence number 
label format 

data type 

data format 
parity/BSN indicator 
retention period 


DH He eb POD HR B&H 


1 file number 


A 2-byte logical file number (LFN) used to refer 
to the file; must be a binary number in the 
range 0 through 255, ASCII blanks (2020) if an 
LFN iS not specified, or -1 (FFFF) if the system 
is to assign an LFN from the pool of available 
LFNS. 


r pathname 


A 4-byte address, which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII space char- 
acter) that when expanded, identifies the file 
to be reserved. Binary zeros in this entry 
indicate that a pathname is not specified. 


oncurrency control 


A l-byte code, applicable only to disk files, 
that specifies the record lock and concurrency 
control to be established for the file. 


If record locking is requested, the records in 
the file will be locked in shared-read/ 
exclusive-write mode when the file is accessed. 
Once a file is reserved with locking, it cannot 
be reserved by another user (task group) unless 
that user also specifies record locking. 
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Bit(s) 


The type of file concurrency chosen indicates 
how you intend to access the file and in what 
way you are willing to share access to the file 
with other users (task groups). There are six 
types of concurrency control, as follows: 


Type 


Type 


Type 


Type 


Type 


Type 


5 - 


You will write or read; others can 
Write or read (read/write sharing) 


You will write or read; others can read 
but not write (read share, exclusive 
write) 


You will write or read; no others can 
write or read (exclusive) 


You will read; others can read and 
write 


You will read; others can read but not 
write (read sharing) 


If the file is already reserved, the 
last concurrency specified is used. If 
the file is not already reserved, type 
3 concurrency control is used. 


The value of the lock/concurrency control byte 
is determined as follows: 


Meaning 


Lock specification: 


0 - Do not lock records 
1 - Lock records 


Must be zero 


Concurrency control specification 


000 - 
001 - 
010 - 
O11 - 
LOC: 
101 - 


Type 
Type 
Type 
Type 
Type 
Type 


OI B® WN FR © 


The following diagram summarizes the lock/ 
concurrency control specifications for each pos- 
Sible value of the lock/concurrency control 


byte 
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Type of 
Byte Value Record Concurrency 
(Hexadecimal) Locking? Control 
00 NO 0 
Ol NO 1 
02 NO 2 
03 NO 3 
04 NO 4 
05 NO 5 
80 YES @ 
81 YES 1 
82 YES 2 
8 3 YES 3 
84 YES 4 
85 YES 5 


mount option 


A l-byte code, applicable to disk files and 
directories, that specifies whether a mount mes- 
Sage is to be issued if the volume is not 
mounted. This byte can have the following 
values: 


O - Return a 020C error code in SR1 if the 
volume containing the file referenced by the 
pathname or LFN is not mounted. 


n - (Where n is any value other than 0.) Issue 
a mount request if the volume containing the 
file referenced by the pathname or LFN is 
not mounted. 


tape block size 


A 2-byte binary value, applicable only to tape 
files, that specifies the size of the block in 
bytes. 


For files with fixed length records, the block 
size is a multiple of the record size plus the 
6-character block Serial number (if specified)... 


For files with variable length records, the 
block size can be any value, but should be at 
least as large as the maximum record size plus 
the 4-character logical record header and the 
6-character block sequence number (if 
specified). 
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The block sequence number is specified by a 4 
value of 2 for the tape parity/BSN indicator a 
(see below). 


The block size entry is ignored if the file is 
not tape resident. 


The block size entry is ignored if block size 
was explicitly specified by a previous GET 
command. 


If the file is not currently reserved and block 
size is not specified (i.e., the field contains 
all zeros), a value is computed based on the 
values for logical record size, tape data 
format, and tape BSN indicator. 


If the file is already reserved and block size 
is not specified, the previously specified or 
computed value is not changed. 


tape logical record size 


A 2-byte binary value, applicable only to tape 
files, that specifies the logical record size in 
bytes. 


The logical record size is the size of the 
longest record in the block, excluding the 
logical record header (if any). 


If this is not a tape file, the tape logical 
record size entry is ignored. 


The logical record size entry is ignored if 
logical record size was explicitly specified by 
a previous GET command. 


If the file is not currently reserved and 
logical record size is not specified (i.e., the 
field contains:‘all zeros), a value is computed 
based on the values for block size, tape data 
format, and tape BSN indicator. 


If the file is already reserved and logical 


record size is not specified, the previously 
specified or computed value is not changed. 


f 

i 

\ ; 

NG . / 
ike gee 
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number of buffers 


A l-byte binary value specifying the number of 
buffers to be allocated for I/O when the file is 
opened for access. The possible values are as 


follows: 
O - None specified; system allocates buffers as 
follows: 


Oo Two buffers are allocated for indexed 
files accessed via data management macro 
calls 


o One buffer is allocated for other disk 
files or tape files accessed via data 
management macro calls 


o No buffers are required for files 


accessed via storage management macro 
calls 


n —- Number of buffers to be uSed to access the 
file when other than the above default 
values are used. When accesSsing a file, 
data management first checks all buffers 
allocated for the file to determine whether 
the relative block or control interval is 
already in memory. Thus, increasing the 
number of buffers for a file being 
accessed randomly may Significantly reduce 
I/O time. 


Buffer space is allocated at open-file time and 
returned at close file time when the file is 
accessed via data management macro calls. 
Buffer space is not required if the file is 
accessed via storage management macro calls. 


This entry does not apply to device files; buf- 
fers are allocated according to information 
specified at system building (buffered or 
unbuffered devices). 


tape file sequence number 


A l-byte binary code, applicable only to tape 
files, that indicates the position of the file 
on an ANSI tape volume; can have the following 
values: 
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OO -—- The desired file is the next file on the 
volume 


FF -— Search for the file in a forward direction 
only 


nn -— Relative sequence number of the file on the 
volume 

If a pathname is specified, it is used with the 

tape file sequence number to perform a file 

Search when an open file macro call is issued. 

(The maximum file name length is 12 characters.) 


See the description of the open file macro call 
(SOPFIL) for a discussion of tape search rules. 


If FF is specified, the search is performed from 
the current position on the volume to EOD. 


If the file is not tape-resident, this entry is 
ignored. 


tape label format 


A l-byte code, applicable only to tape files, 
that indicates the tape label format. 


Q - No label format specified (can be labeled or 
unlabeled) 


1 - Tape has standard labels 
2 - Tape is not labeled 


If the file is not tape-resident, this entry is 
ignored. 


tape data type 


A l1-byte code, applicable only to tape files, 
that specifies the data type. 


0 - No data type specified 
1 —- Honeywell 
2 - ANSI Level 3 


If the file is not tape-resident, this entry is 
ignored. 
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tape data format 


A l1-byte code, applicable only to tape files, 
that indicates the data format. 


- No format specified 

- Fixed length records 

- Variable length records 
- Undefined records 


WNMrF © 


If the file is not tape-resident, this entry is 
ignored. 


tape parity/BSN indicator 


Bit(s) 


0, 


2, 


i! 


3 


A l-byte code, applicable only to tape files, 
that indicates whether the tape has odd or even 
parity, and whether each block on the tape has a 
six-character block sequence number (BSN) in the 
First six characters of the block. 


Meaning 
Must be 0. 
O = Parity not specified. 
1 = Odd parity. 
2 = Even parity. 


These bits are meaningful only for 
7-track tapes to be opened for 
Storage management (block level) 
access. 


Must be 0. 


No BSN specified. 
BSN not supplied. 


0 
1 
2 BSN supplied. 


If 2 is specified, a block sequence number is 
assumed to be present on input; on output a 


block sequence number will be inserted. 


If the file is not tape-resident, this entry is 
ignored. 
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tape retention period 


A 4-byte value, applicable only to tape files, 
that specifies the tape retention period in 
days. Zeros in this field indicate that the 
retention period is not specified. 


If the file is not tape-resident, this entry is 
ignored. 


FUNCTION DESCRIPTION: 


This macro call reserves the file with proper access rights 
for use by the data management and storage macro calls. It 
can also be used to alter concurrency or tape definition 
arguments established by a previous get file macro call, 
provided the file is not already open (see the open file 
macro call) in the task group in which you are executing. 


Once you have reserved a file, it cannot be released (see 
the release file macro call) by a task executing in another 
task group until you are finished with it (i.e., until you 
issue a remove file macro call). 


The file can be specified (in the argument structure) by an 
LFN only, a pathname only, or both an LFN and a pathname. 


o If specified only by an LFN, the LFN must have been pre- 
viously associated with a pathname (See the associate 
file macro call), or it must have been previously 
assigned to the file through the get file or create file 
function. 


o If only a pathname is specified, the file is reserved 


without a unique LFN. The only requests that can use the 


File are those that can reference the file by a pathname 
only, i.e., SGTFIL, SGIFIL, SRLFIL, SRMFIL. 


o If a pathname is specified and the LFN field contains a 
value of -1l (FFFF), the system assigns a unique LFN from 
the task's LFN pool. In this case it is your responsi- 
bility to return the LFN to the pool (by a remove file 


macro call) when the LFN is no longer needed. In assign- 


ing a unique LFN from the pool, the system selects the 
highest LFN available for assignment and sets it in the 
LFN entry in the argument structure, overlaying the pre- 


vious contents (FFFF). You must move this value to other 


Structures (argument structures or FIBS) as required. | 
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o If both an LFN and a pathname are specified, the file is 
reserved and assigned to the LFN. This LFN-to-file 
assignment remains in effect until the file is removed 
from the task group or another get file macro that 
Specifies the same LFN is issued. 


The get file macro call allows you to append ASCII charac- 
ters to a previously associated pathname or a partial path- 
name (see the associate file macro call). You do this by 
prefixing the string of characters to be appended (i.e., 
pointed to by the pathname pointer entry) with a colon (:). 
The system replaces the colon with the previously associated 
pathname, as follows: 


Previously Characters 


Associated to be 

Pathname Appended _ Result 

none : Working directory 
none :ABC ABC 
AVOL1>UDD >>FILEO] VOL1>UDD>FILEO1 
AVOL2> > FILEO2 AVOL2>F ILEO2 


As stated above, the get file macro call can be used to 
alter concurrency control. In doing so, note the 
following: | 


o If you specify type 0 concurency control the first time 
the file is reserved in a task group, the system reserves 
the file for exclusive use (type 3 concurrency). 


o If you specify type 0 concurrency control and the file 
was previously reserved in this task group, the previous 
concurrency control does not change. This could occur if 
you wanted to change the tape file definition argument or 
address the file through a different LFN. 


o A get file macro call does not alter the concurrency con- 
trol established through a previously issued GET command. 
Only by issuing another GET command can you alter the 
concurrency eStablished through a previous GET command. 


o If device level access is desired (i.e., the pathname is 
in the form >SPD>dev_name[>volid]), the following rules 
apply: 

- Type 3 exclusive concurrency control is set regardless 
of the value specified in concurrency control entry if 
the pathname is specified as: 


>2SPD>dev_name 
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No volume label validation is performed. Note that 
tapes are always reserved with type 3 concurrency. 


- For disk volumes type 2 concurrency control is set 
regardless of the value specified in the concurrency 
control entry if the pathname is specified as: 


>SPD>dev_name>volid 


The volume label is read and validated; if a mismatch 
occurs, the action specified in the mount option argu- 
ment occurs. 


- To change disk device-level concurrency control, you 
must first issue a remove file macro call and then 
issue a new get file macro call. 


o The following rules apply to directories reserved through 
a get file macro call: 


- If the directory is reserved exclusively (type 3 con- 
trol), all subdirectories and files inferior to the 
directory are also held exclusively. For example, a 
get file macro call having a pathname of “volid (i.e., 
only the volume directory supplied) and a concurrency 
of 3, would reserve the entire volume for exclusive 
use through normal file, data, and storage management 
facilities. This is not the same as device level 
access (>SPD>dev name) Since it permits normal access 
by the user at the file level. 


- If the directory is not reserved exclusively, read/ 
write share concurrency control (type 5) is set 
regardless of the specified value. 


- Directory-level concurrency cannot be changed by 
issuing a new get file macro call. To change 
directory-level concurrency, you must first issue a 
remove file macro call and then a get file macro call. 


The record lock facility is a mechanism that provides multi- 
user interference protection for shared file access. When a 
record is accessed by a task group, it is locked (by locking 
the control interval(s) in which the record is contained) on 
a first-come first-served basis. If another user is sharing 
the file, he will be denied access to the record (and any 
other record contained in the same control interval) until 
the previous user unlocks the record (through the SCLPNT 
macro call). You should consider the following points when 
uSing record locking: 
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An LFN within a task group uniquely identifies a user for 
record locking purposes and thus provides interference 
protection between task groups. Since tasks within a 
task group may agree to access a file through different 
LFNs, interference protection is provided when the 
cooperating tasks agree to respect the LFN assignments. 


Lock requests are valid only for disk resident files (a 
request to lock any other file is ignored). Directories 
and entire disk volumes cannot be reserved with lock. 
The primary index of an indexed file is never locked 
(Since once created, it is never updated). 


Files reserved with lock cannot be modified (written) via 
Storage management access. 


Records are locked in "Shared read/exclusive write" mode, 
which can be explained as follows: 


- For purposes of record locking, file system users may 
be classified as "readers" and “updaters." Readers 
are those who have opened the file, but without update 
permission, Since they need only to read records. 

They are not concerned if other users are reading the 
Same record, but do not want to read a record while it 
is being updated. 


- Updaters have opened a file, with update permission, 
and want to be the only users of a specific record. 
The record lock facility makes sure that a given 
record is accessed by only one updater or by n readers 
at one time. 


- Accordingly, readers set read locks, updaters set 
write locks. A given record may have any number of 
read locks, or it may have only one write lock. 


Once specified, locking is automatic. Any access (read 
or write) will cause an appropriate lock. The number of 
locks that can exist at one time is limited only by the 
amount of memory dedicated to the lock pool (i.e., the 
area of memory where locked records are recorded). (This 
area is defined at system building; see the System 


Building manual.) 


Any access that encounters a lock conflict is not per- 
formed. The caller is notified immediately; no wait is 
performed. 
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o Once a file has been reserved as sharable with record 
locking, all users who want to share access to the file 
must also request record locking. Conversely, if a 
Sharable file is initially reserved without record lock- 
ing, no user who specifies record locking is allowed to 
access the file. In other words, bit 0 of the lock/ 
concurrency control argument must be identical in the get 
file macro calls, with the following exceptions: 


- If bits 5 through 7 of the lock/concurrency control 
argument specify type 2 concurrency control (you read, 
others read and write), bit O need not match in the 
SGTFIL macro calls. Thus, the user who specifies type 
2 concurrency control can gain access to records that 
are currently locked by another user. However, this 
user can only read, and the integrity of the data is 
not guaranteed. 


- If the entire lock/concurrency control byte is all 0 
bits, the lock and concurrency states set by a GET 
command or a previous SGTFIL macro call in the same 
task group are inherited. 


o The SCLPNT macro call is used to unlock records. If 
records are not unlocked, lock pool overflow or a dead- 
lock record condition will probably result. (See the 
clean point macro call for details.) 


o You must provide for all actions to be taken when noti- 
fied of lock pool overflow or record lock concurrency 
conflict. When a record deadlock condition occurs, you 
should restart the current phase by unlocking all records 
and recycling to the point where the interrupted sequence 
began. (In so doing some records may be updated, thereby 
making a Simple recycling unsatisfactory.) From a 
practical standpoint, all records to be updated or 
deleted should be read first to ensure access; all 
inserts should be done first to make the unwinding of a 
transaction easier to manage. 


If an operator terminal is not included in the system, or if 
messages to the operator terminal have been Suppressed 
(through a SCMSUP macro call), a S$GTFIL macro call issued to 
reserve a volume that is not mounted results in an 020C 
(volume not mounted) error return. 


If a file is reserved through an LFN and a subsequent SGTFIL 
macro call is issued specifying the same LFN, this LFN 
becomes associated with the new file. The previously 
reserved file will remain reserved for the task group until 
it 1S removed (through the remove file macro call). 
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Since the get file macro call performs so many functions, it 
should be used as infrequently as possible. A SGTFIL fol- 
lowed by multiple SOPFIL/SCLFIL sequences is much more 
efficient than a $GTFIL, SOPFIL, SCLFIL, SRMFIL, S$GTFIL, 
etc. 


Offsets tags for the argument structure block can be defined 
by the SGTPSB macro call. 


Tape file arguments are meaningful in only when (1) a 
labeled tape file is being created (opened) in RENEW mode; 
and (2) an unlabeled tape file is being processed for input/ 
output. For labeled tapes being opened for input (PRESERVE 
mode), the various tape parameters are taken from the file 
header labels. 


For tape files, default block size (BKSZ) and logical record 
size (LRSZ) are computed as shown in the following diagram: 


BKSZ NOT SPECIFIED BKSZ NOT SPECIFIED BKSZ SPECIFIED 
LRSZ NOT SPECIFIED LRSZ SPECIFIED LRSZ NOT SPECIFIED 


n= 1024 n= LRSZ n= BKSZ 


Opt 
si 
6 


ERROR 
NO YES 
YES 
inne n=n—4 
NO 
YES NO 
ERROR 


YES 
n=nt6 
n=n—6 
BKSZ =n LRSZ=n 
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Block and record sizes are checked for validity as shown in 
the following diagram: 


BKSZ SPECIFIED 
LRSZ SPECIFIED 


YES NO 
| ERROR 


ERROR 


YES 
YES NO 
ERROR 
YES 
NO 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, SB4 is assumed to contain 
the address of the argument structure. 


2. On return, $R1 contains one of the following 
statuS codes: 


0000 -— No error 

0201 - Illegal pathname 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 


0208 —- LFN or file currently open in same task 
group 


D=L38 CBO08 


Example 1: 


0209 
O20C 
0211 


0213 


0222 


0225 


0226 


O22A 


022C 


O22E 


0238 


Named file or directory not found 

Volume not found 

Unable to establish a unique LFN 

Cannot provide requested file concurrency 


Pathname cannot be expanded, no working 
directory 


Not enough system memory for buffers or 
structures 


Record lock concurrency conflict 

Record lock area overflow or not defined 
Access control list violation 

Record lock concurrency conflict 


Invalid file description 


In addition to the above codes, any system 
service codes received through the file manager 
are passed on through SRl. 


In the following example, the get file macro call identifies 
an argument structure that contains the appropriate argu- 
ments to reserve the indexed file created in the example for 
the create file macro call (i.e., FILE A) with type 5 con- 


currency control 


WRTFIL 


DC 
RESV 
DC 


RESV 
DC 
RESV 


(read/write share) and record locking. The 
argument structure was built as follows: 


Z‘'OO0O5' See "Assumptions for File 
System Examples" in Section 3. 
(The pathname is defined in 
the example for the create 
file macro call.) 

<IDXO1 

2-SAF 

Z'8501' READ/WRITE SHARE; RECORD 
LOCKING: ISSUE MOUNT REQUEST 

2,0 IGNORED 

Z‘'0O200' BUFFERS=2 

4,0 IGNORED 
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It is assumed that the following macro calls were issued 
before the SGTFIL macro call was issued: 


SCRDIR ! SUBDIR (See create directory macro example) 


SCRFIL IFILE A (See "Assumptions for File System 
Examples") 


The SGTFIL macro call altering FILE A concurrency from 
exclusive to share can be specified as follows: 


SGTFIL IWRTFIL 
Example 2: 


In this example, the SGTFIL macro call is used to append 
characters to an incomplete pathname defined as follows: 


DIRPTH DC 'AVOLO3>SUBINDEX.AA! (See create direc- 
tory macro example) 


This pathname has been associated with the LFN as follows: 


SASFIL !FILE X 


where the argument structure labeled FILE X has been defined 
as follows: an 


FILE X DC Z'OOA3' #£LFN=163 
DC <DIRPTH  PATHNAME '‘\VOL03 SUBINDEX.AA! 
RESV 2-SAF 


Assuming that the above definitions have been made, the 
following argument structure identifies the characters to be 
appended to the incomplete path (DIRPTH): 


WTFIL2 DC Z‘OOA3' LFN=163 
DC <IDXO2 PATHNAME POINTER 
RESV 2-SAF 
DC Z'O301' EXCLUSIVE: ISSUE MOUNT REQUEST 
RESV 2,0 UNS PECIF IED 
DC Z‘'Q200' BUFFERS=2 
RES V 4,0 IGNORED 


The pathname labeled IDX02 is defined as follows: 


IDX02 DC ';>FILE CA! 
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The result of specifying the above structure (WTFIL2) in the 
following SGTFIL macro call is to reserve the file ident1- 


fied by the pathname “VOLO03>SUBINDEX.A>FILE C with exclusive 
concurrency control: 


SGTFIL IWTFIL2 
However, before you can open and access FILE C, it must 


exist in the file system hierarchy (i.e., it must have been 
created as defined in the create file macro call example). 
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GET FILE PARAMETER STRUCTURE 
BLOCK OFFSETS | 


GET FILE PARAMETER STRUCTURE BLOCK OFFSETS 
Macro Call Name: S$GTPSB 

Associated Macro Call: SGTFIL 

Generated Offsets Tags: 


Corresponding 


Offsets 

Tag _(in words) Entry Name 
G LFN 0 Logical file number (LFN) 

G PTHP +] Pointer to pathname 
G CONC +3 Concurrency control (first byte) 

G MNT +3 Mount option (second byte) 
G BLSZ +4 Tape block size 

G LRSZ +5 Tape logical record size 
G NBF +6 Number of buffers (first byte) 
G_TFSN +6 Tape file sequence number (second byte) 
G TLF +7 Tape label format (first byte) 

G TDT +7 Tape data types (second byte) 
G TDF +8 Tape data format (first byte) 

G BSN +8 Tape BSN indicator (Second byte) 
G _TRP +9 Tape retention period 

G SZ +11 Size of structure (in words); not a 


field in the block 
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GET FILE INFORMATION 


GET FILE INFORMATION 
Macro Call Name: $GIFIL 
Function Code: 10/60 
Equivalent Command: None 


Retrieves information about the specified file. You iden- 
tify the file by supplying either a logical file number 
(LFN) or a pathname. This macro call returns information 
such as file type, device type, and, optionally, other file 
attributes (logical record size, block or control interval 
size, space allocation, etc.). In addition, you can 
receive a description of the keys of an indexed file. 


FORMAT: 


[label] S$GIFIL fargument structure address] 


ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. (Entries marked 
with an asterisk (*) are provided by the system. You 
must supply the other entries.) The size of each 


entry, whose descriptions follow this list, is as 
follows: 
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Size ! 
Argument Structure Entry (in bytes) Sear 


logical file number 
*pointer pathname 
*device type 

*logical resource number 
*file type 

*data format 

file attribute pointer | 
reserved 4 (all zeros) 
key descriptor pointer 

reserved | 4 (all zeros) 


Mm er hh) BN 


logical file number 


A 2-byte logical file number (LFN) used to refer 
to the file; must be a binary number in the 
range 0 through 255, or ASCII blanks (2020), 
which indicates that an LFN is not specified. 

If this entry contains blanks, the pathname- 
pointer entry (below) must point to a pathname. 


*pointer pathname 


A 4-byte address, which may be any address form 
valid for an address register. If an LFN is . 
specified in the first entry, this entry ee, 
(optionally) points to a 58-byte field in main 
memory into which the system places the full 
absolute pathname associated with the LFN. If 
the LFN entry contains ASCII blanks, this entry 
points to the location where a pathname (which 
must end with an ASCII space character) is 
found. This pathname identifies the file for 
which the system is to retrieve information. 
Zeros in this entry indicate that the pathname 
is not to be returned. If zeros are specified, 
the LFN entry (above) must contain a nonblank 
value. 


*device type 


A 2-byte entry into which the system places the 
4-digit hexadecimal device code of the device 
containing the file. The devices, their codes, 
and marketing identifiers are: 
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Device 
Type 


Peripheral Device Code 


Teleprinter 2018 
2019 


Marketing Identifier 


TTUDLO2 
TTUQ101 


CRT Keyboard Console 2020 DKU 9101 | 
Keyboard Typewriter Console 2018 TWU9101 


Cartridge Disk 


Serial Printer 2004 
2006 


Line Printer 
: 
‘ 


Magnetic Tape 
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CDUIIOL 


CDU 9102 


| CDU 9103 


CDU 9104 


PRU 9101 
PRU9102 


PRU 9104/9106 
same aS above but with 
Option PRF9102 
PRU 9103/9105 

same as above but with 
Option PRF9102 


MTU 9104 
45-ips) 
MTU 9105 
75-ips) 
MTU 9109 
bpl, 
MTU 9109 
bpi PE, 
MTU 9110 


bpi NRZI, 


MTU 9110 
bpi PE, 
MTU 9112 
bpi) 
MTU 9112 
bpi) 
MTU 9113 
bpi) 
MTU 9113 
bpi) 


NRZI, 


(9-track NRZI, 


(9-track NRZI, 


(9-track, 


(9-track, 
45-ips) 

(9-track, 
75-ips) 
(9-track, 
75-ips) 

(7-track, 


(7-track, 


(7-track, 


(7-track, 


45-ips) 


800 


1600 


800 


1600 


900= 


800- 


556- 


800- 
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Device 


Type 
Peripheral Device Code Marketing Identifier 


Magnetic Tape (cont) MTU9114 (9-track, 1600- 
bpi, 45-ips) 
MTU9115 (9-track, 1600- 
bpi, 75-ips) 


Mass Storage Unit MSU9101/9105 (40- 
| megabyte) |. 

MSU 9102/9106 (80- 
megabyte) 
MSU9103 (143/127- 
megabyte) 
MSU9104 (288/256- 
megabyte) 


Card Reader/Punch 2088 CCU 9101 /PCU 9101 


*logical resource number 


A 2-byte entry into which the system places the 
logical resource number (LRN) that corresponds 
to the device on which the specified file is 
located. 


*file type 


A l-byte entry into which the system places a 
code identifying the file organization of the 
specified file, as follows: 


-~ IBM diskette 

- Device file 

- Fixed-relative without deletable records 
- Fixed-relative with deletable records 
Directory 

- Relative 

- Sequential 

- Indexed 

- Tape-resident file 


MH NnNDWOUMNNOF 
| 


*data format 


A 1l-byte entry into which the system places a 
code identifying the format of the data, as 
follows: 


F —- Fixed-length record 


D - Variable-length record (decimal count siZe) 
U - Undefined 
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File attribute pointer 


A 4-byte address of a 32-byte field in main 
memory into which the system can place file- 
attribute information, as described below; may 
be any address form valid for an address regis- 
ter or zeros, which indicate that the informa- 
tion is not required. 


reserved 


A 4-byte entry, containing zeros. 


key descriptor pointer 


A 4-byte address of an 18-byte field in main 
memory into which the system can place key- 
descriptor information, as described below; may 
be any address form valid for an address regis- 


ter, or zeros, which indicate that the informa- 
tion is not required. 


reserved 
A 4-byte entry, containing zeros. 
The system places file attribute information in the 32-byte 


field pointed to by the file attribute entry described 


above. For disk-resident files, the structure contains the 
following: 


*logical record size 


A 2-byte entry specifying the maximum size (in 
bytes) of logical records stored in the file; 
the size does not include headers. 

*control interval/physical sector size 


A 2-byte entry, as follows: 


For fixed-relative files: the size (in bytes) 
of a physical sector. 


For all other files: the size (in bytes) of a 


control interval, including control interval and 
logical-record headers. 
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*current allocation size 


A 2-byte entry specifying the number of active 
control intervals. This value may be less than 
the currently allocated space. 


*allocation increment size 


A 2-byte entry specifying the number of addi- 
tional control intervals to be allocated to the 
file when it is necessary to do so. This value 
is the size of an additional extent to be added 
to the file. 


*maximum allocation size 
A 2-byte entry specifying the maximum number of 
control intervals that can be allocated to the 
File; indicates the limit to which the file can 
grow. Zeros indicate there is no defined limit. 

*amount of free space per control interval 
A 2-byte entry, as follows: 
For indexed files: the number of bytes to be 
left free in each control interval at file load- 
ing time; this value supplies space for records 
to be inserted without causing overflow. 
For all other files: contains zeros. 

*local overflow allocation increment 
For indexed files: a 2-byte value that sets the 
frequency at which a local overflow control 
interval will be allocated when the file is 
loaded. For example, if this value is 10, one 
local overflow control interval will be allo- 
cated after every ten data control intervals 
allocated. 
For all other files: contains zeros. 

*number of keys 


A 2-byte entry that contains a 1 for indexed 
files, and a O for all other files. 


*reserved 


A l6-byte field containing zeros. 
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oe 


For tape-resident files, the structure contains the follow- 
ing information: 


*logical record size 


A 2-byte entry specifying the maximum size (in 
bytes) of logical records stored in the file; 
the size does not include headers. 


*block size 


A 2-byte entry specifying the maximum size (in 
bytes) of a block, including block and logical- 
record headers. 


*reserved 


A 28-byte entry containing zeros. 


For device files, the structure contains the following 
information: 


*logical record size 


A 2-byte entry specifying the maximum size (in 
bytes) of a logical record (i.e., the unit of 
transfer to the device file). 


* block size 


A 2-byte entry specifying the maximum size (in 
bytes) of a physical record (i.e., the unit of 
transfer to a device file). 


*reserved 


A 28-byte entry containing zeros. 
The following key descriptor information is placed in the 
18-byte field pointed to by the key descriptors entry 
described above. This structure applies only to indexed 
files, and contains the following: 
*reserved 


A 4-byte entry that contains Z'OOOOFFFF'. 


*reserved. 


A l-byte entry that contains l. 
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* reserved 
A 9-byte entry that contains zeros. 
*key component data type 


A l-byte entry that indicates the data type of 
the key component. The entry is hexadecimal 43 
(i.e., C) for character, or hexadecimal 44 
(i.e., D) for decimal. 


*key component size 


A l-byte entry that specifies the size of the 
key component in bytes; that is, it specifies 
the size of the primary key stored in each 
logical record in the indexed file. 


*key component location 


A 2-byte entry that specifies the offset (in 
bytes) from the beginning of the record to the 
beginning of the key field; the first byte in 
the logical record is position l. 


FUNCTION DESCRIPTION: 


Before this macro call is issued, tape-resident files must 
be open (see the open file macro call) so that the system 
can retrieve the file attribute information. (File attri- 
bute information is stored in the tape labels.) 


If neither the pathname nor the LFN is specified, a status 
code of 0205 is returned. 


If an LFN is specified, the file must have been previously 
reserved through that LFN via a get file or create file 
macro call (or equivalent command). 


To access specific entries in the argument structure, use 
the SGIPSB, S$SGIKDB, and SGIFAB macro calls. 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the parameter structure. 


2. On return, $R1 contains one of the following 
Status codes: 
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Example: 


0238 


No error 

Illegal pathname 

Illegal argument 

Unknown or illegal LFN 

Named file or directory not found 
Volume not found 


Pathname cannot be expanded, no current 
working directory 


Not enough system memory for buffers or 
Structures 


Not enough user memory for buffers or 
structures 


Illegal file type 
Access control list (ACL) violation 


Invalid file description 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


In this example, the get file information macro call is used 
to obtain information about the file reserved in the example 


for the get file macro call. 
defined as follows: 


F INFO 


PATH 5 
FILATT 


The argument structure is 


5 LFN=5 
<PATH5 POINTER TO PATHNAME 
2-SAF 
3,0 DEV. TYPE, LRN, 
FILE/RECORD TYPE INFOR AREA 
<FILATT POINTER TO FILE ATTRIBUTE AREA 
2- SAF 
6,0 RESERVED 
29,0 FIELD TO RECEIVE PATH 
16,0 FIELD TO RECEIVE FILE ATTRIBUTE INFO 
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Since, as stated under “Assumptions for File System 
Examples" (in Section 3), the SGIPSB and SGIFAB macro calls 
have been included in your procedure, you can reference any 


entry in F INFO and FILATT after executing the following 
macro call: 


SGIFIL !F INFO 
The following instructions allow the reference to be made: 


LAB $B6,F INFO 
LAB $B7,FILATT 


Then, for example, to reference the system-sSupplied logical 
resource number and control interval size, respectively, you 


would specify the following address syllables in your 
instructions: 


SB6.1_ LRN SYSTEM-SUPPLIED LRN 
$B7.K CISZ SYSTEM-SUPPLIED C.I. SIZE 
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GET FILE INFORMATION, 
FILE ATTRIBUTE BLOCK OFFSETS 


GET FILE INFORMATION, FILE ATTRIBUTE BLOCK OFFSETS 


Macro Call Name: SGIFAB 


Associated Macro Call: SGIFIL 


Generated Offsets Tags: 


For tape-resident and device files: 


Corresponding 


Offsets 
Tag (in words) 
T LRSZ 0 
T BKSZ +1 
T RFU +2 
T SZ +16 


Entry Name 


Logical record size 
Block size 
Reserved 


Size of Structure (in words); 
not a field in the block 


For disk-resident files: 


Corresponding 


Offsets 
Tag (in words) 
K LRSZ 0 
kK CiSZ +1 
K CASZ +2 
K AISZ +3 
K MASZ +4 
K_ FREE +5 
K LOV +6 
K NKS +7 
K SZ +16 


Entry Name 


Logical record size 

Control interval/physical sector size 
Current allocation size 

Allocation increment size 

Maximum allocation size 

Amount of free space per C.I. 

Local overflow allocation increment 
Number of keys 


Size of structure (in words); not a 
field in the block 
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GET FILE INFORMATION, | 
KEY DESCRIPTORS BLOCK OFFSETS 


GET FILE INFORMATION, KEY DESCRIPTORS BLOCK OFFSETS 
Macro Call Name: SGIKDB 

Associated Macro Call: SGIFIL 

Generated Offsets Tags: 


Corresponding 


Offsets 

Tag (in words) Entry Name 
Y RFUIL om Reserved 

YR +] Record-type oo 
Y NKC +2 Number of key components 

Y RFU2 +3 Reserved 
Y KLEN. +7 Key type and size in bytes 

Y KOFF +8 Key offset in bytes 

Y SZ +9 Size of structure (in words); 


not a field in the block 
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GET FILE INFORMATION, 
PARAMETER STRUCTURE BLOCK OFFSETS 


GET FILE INFORMATION, PARAMETER STRUCTURE BLOCK OFFSETS 
Macro Call Name: SGIPSB 

Associated Macro Call: SGIFIL 

Generated Offsets Tags: 


Corresponding 


Offsets 
Tag (in words) Entry Name 
I LFN 0 Logical file number (LFN) 
I PTHP +1 Pointer to pathname 
I DTYP +3 Device type 
I LRN +4 Logical resource number 
I FTYP +5 File type (first byte) 
I -RTYP +5 Data format (second byte) 
I FABP +6 Pointer to file attributes 
7” (see SGIFAB description) 
I FSTP +8 Reserved 
I KDP +10 Pointer to key descriptors 
7 (see SGIKDB description) 
I RFU2 +12 Reserved 
I 8z +14 Size of structure (in words); 


not a field in the block 
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GET MEMORY/GET AVAILABLE MEMORY 


GET MEMORY /GET AVAILABLE MEMORY 


Macro Call Name: SGMEM 


Function Code: 04/02 (get memory), 04/03 (get available memory) 


Equivalent Command: None 


Allocate to the issuing task the requested amount of contig- 
uouS memory. The memory is allocated as a block from the 
memory pool of the task group to which the issuing task 
belongs. If the specified amount of contiguous memory is 
not available, perform one of the following actions: 


o Return immediately to the issuing task without performing 
any allocation (get memory with DENY specified). 


o Suspend the issuing task until the required memory 
becomes available (get memory with WAIT specified). 


o Allocate the largest contiguous block of memory currently 
available in the memory pool and return to the issuing 
task (get available memory (AVAIL) specified). 


FORMAT : 


[label] SGMEM location of maximum number of words required 
DENY 
,1\ WAIT 
AVAIL 
ARGUMENT DESCRIPTION: 


location of maximum number of words required 


Any address form valid for a data register; provides 
the maximum number of words of memory to be allocated 
as a block to the issuing task. The value used cannot 
exceed the size of the pool minus the memory block 
header. (Each bit in the bit map represents a 32-word 
allocation.) The value for the number of words cannot 
exceed 1,048,575 (minus the memory block header). 
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ae 


DENY 


If the number of words of memory specified in argu- 
ment 1 is not available either in the task group's 
or, if it can extend into it, the batch group's 
memory pool, return immediately to the issuing task. 
If argument 2 is omitted, DENY is the default value. 


WAIT 


If the number of words of memory specified in argument 
1 is not available either in the task group's or, if 
it can extend into it, the batch group's memory pool, 
suspend the issuing task until the memory becomes 
available. Activate the task, allocate the memory, 
and return to the task. 


AVAIL 


If the number of words of memory specified in argument 
1 is not available in the task group's memory pool, 
allocate to the issuing task the largest contiguous 
block of memory currently available. 


This function will not obtain memory from the batch 
pool, even if the online pool may extend into the 
batch pool. 


FUNCTION DESCRIPTION: 


This call allows the issuing task to dynamically obtain a 
block of memory from the task group'’sS memory pool. If argu- 
ment 2 is DENY, the task obtains a block of the specified 
size or no block at all. If argument 2 is WAIT, the task is 
Suspended until the requested amount of memory becomes 
available. If the online pool extended into the batch pool, 
allocated memory may be from the batch pool, which may have 
been rolled out because of this request. 


If argument 2 is AVAIL, the task obtains a block of the 
specified size or the largest block (less than the specified 
Size) that is currently available. 


When AVAIL (get available memory) is specified, the actual 
Size of the memory block allocated may be much smaller than 
the desired size. This situation occurs because the memory 
manager does not wait for memory to become available. 
Rather, it checks for contiguous memory of the specified 
Size and if none is available, allocates the largest contig- 
uouS block of memory that is available. If no memory is 
available, the system returns a status code of 0602. 
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NOTE: When AVAIL is specified, all of available 
memory may be removed from the pool. Other 
functions (including the command processor) 
that require memory from that pool then will 
not be able to execute until memory becomes 
available. 


When a return is made to the issuing task, the actual size 
of the supplied contiguous memory block is placed in S$R6 and 
SR7. “Actual size" has the following meaning: Memory is 
allocated in units of 32 words; a block of memory contains 
an integral number of 32-word allocation units. A memory 
block also contains a header; its size is two words in SAF 
mode and three words in LAF mode. The value returned in SR6 
and S$R7 is the specified number of words rounded up to the 
next higher allocation unit, minus the size of the memory 
block header. 


NOTE: If AVAIL is specified and a block of the 
requested size could not be found, the actual 
Size of the block is that of the largest 
contiguous memory block available, minus the 
size of the header. 


The maximum size of a memory block that can be obtained is 


1,048,575 words, minus the memory block header. The block 
size cannot exceed the pool size. 


On return to the issuing task, $B4 contains the address of 
the first usable word in the block (first word after the 
block header). 


The get memory/get available memory functions enable the 
task to dynamically acquire additional memory in response to 
processing needs. When a memory block is no longer 
required, it must be returned to the task group's memory 
pool (by a return memory or return partial block of memory 
macro call). If a task repeatedly acquires memory blocks 
and does not return them, the task group memory area will 
become empty (or nearly so), denying other tasks the oppor- 
tunity to obtain memory blocks. 


NOTES: 1. The number of contiguous words of memory 
required, supplied by argument 1, is placed in 
SR6 and SR7; if this argument is =SR7, it is 
assumed that S$R6 and $R7 contain the number of 
words desired. 


2. If argument 2 is DENY, S$R2 is set to 0. MIE£ 
argument 2 is WAIT, S$R2 is set to -l. If argu- 
ment 2 is AVAIL, S$R2 is not set. If argument 2 
is omitted, S$R2 is set to 0 (DENY). 


3=L58 CB08 


pale” ONS 


3. On return to the issuing task, $R1, $R6, SR7, 
and $B4 contain the following information: 


SR1 - Return status; one of the following: 


0000 - If the call specified WAIT or DENY, 
a successful allocation was made; 
if the call specified AVAIL, at 
least one memory unit was allocated 


0601 - If the call specified WAIT or DENY, 
requested contiguous memory exceeds 
defined pool size; not applicable 
if the call specified AVAIL 


0602 - If the call specified WAIT or DENY, 
the requested contiguous memory 
could not be obtained; if the call 
specified AVAIL, no memory alloca- 
tion units were available 


The following codes could be returned if 
WAIT or DENY was specified. 


0818 - No task group with specified group 
id exists (System software error) 


O81A - Suspend in progress (system soft- 
ware error) 


0O81B - Rollout of online task group 
attempted (system software error) 


081D - Batch task group already rolled out 
(system software error) 


O81E - Unrecoverable media error during 
rollout 
SR6, SR7 - Actual size of contiguous memory 


blocks supplied, rounded up to the nearest 
multiple of 32 words | 


SB4 - If SR1 was 0000, address of first avail- 
able word in memory block 
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Examples: 


In this example, the SGMEM macro call is used to attempt to 
obtain 2500 words of memory from the issuing task group's 
memory area. If the memory is available, the system will 
return with a status of 0000 in SR1l, the actual size of the 
memory area obtained in $R6 and SR7, and the address of the 
first usable word of the area in $B4. The example saves the 
address of the memory area in the field labeled M PTR and 
continues processing. If 2500 contiguous words of memory 
are not available, the system will return with a status of 
0602 in SRl. If the pool size is less than 2500 words, the 
system will return error code 0601 in SRI. 


SGMEM =2500 

BNEZ SR1,NO MEM 

STB SB4,M PTR 
M PTR DC <$ 


In this example, the SGMEM macro call is used to attempt to 
obtain the largest contiguous area of memory, not exceeding 
5000 words, available in the issuing task group's memory 
area. If any memory is available, the system will return 
with a status of 0000 in S$R1, the actual size of the memory 
area obtained in SR6 and SR7, and the address of the first 
usable word of the area in S$B4. If all of the memory in 
the task group'S memory area is in use at the time, the 
system returns with a status of 0602 in SRI. 


SGMEM =5000,AVAIL 
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( GET WORKING DIRECTORY 


GET WORKING DIRECTORY 

Macro Call Name: SGWDIR 

Function Code: 10/C0O 

Equivalent Command: List Working Directory (LWD) 


Returns the name of the current working directory. This 
function is usually done outside program execution. 


FORMAT: 
[label] S$GWDIR [argument structure address] 
ARGUMENT DESCRIPTION: 


argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entry. 


working directory pathname 


A 45-byte field, in main memory, into which the 
system can place the full absolute pathname of 
the current working directory. 


FUNCTION DESCRIPTION: 


This macro call returns the full absolute pathname of your 
current working directory. Although the pathname may be 
Shorter than the maximum 45 characters, the argument struc- 
ture must be large enough to accommodate the maximum number 
of characters. 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, S$B4 is assumed to contain 
the address of the argument structure. 
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2.e On return, SR1 contains one of the following 
status codes: 


0OQccO — No error 


0201 - Illegal pathname 
0205 - Illegal argument 
0222 - Pathname cannot be expanded, no working 


directory 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 
This example assumes the following file system hierarchy 


(see the System Concepts manual) and that the working direc- 
tory is 'SUB.DIR.BBI1’. 


VOLO] 
SUB.DIR.A SUB.DIR.B 
| 
SUB.DIR.AA FILEO1 SUB.DIR.BB 
| (—e 
FILEO2 FILEO3 SUB.DIR.BB1 


—__—__, 
FILEO4 SUB.DIR.B1B 
| 
FILEOS 


Coding the SGWDIR macro call causes the system to place the 
full absolute pathname of the working directory; defined 
below, into the specified argument structure: 

SGWDIR !CURDIR 

CURDIR RESV 29 


The path placed in the main memory field labeled CURDIR is: 


“VOLO1>SUB. DIR. B>SUB.DIR. BB>SUB. DIR. BBLAAAAAAAAAAAAAAAAAAA 
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HOME DIRECTORY 


HOME DIRECTORY 

Macro Call Name: SHDIR 
Function Code: 14/0B 
Equivalent Command: None 


Return the pathname of the initial working directory of the 
calling task group to a 45-character receiving field. 


FORMAT: 


[label] SHDIR [location of home directory field address] 
ARGUMENT DESCRIPTION: 
location of home directory field address 


Any address form valid for an address register; pro- 
vides the address of a 45-character, aligned, non- 
varying field into which the system will place the 
pathname of the default working directory of the 
calling task group. 


FUNCTION DESCRIPTION: 


This call returns the pathname of the initial working 
directory to a field in the issuing task. The pathname 
returned is that specified in the -HD argument of the login 
command. If the -HD argument was not specified, the path- 
name returned is that set according to uSer registration 
arguments or system defaults. 


NOTES: 1. The address of the receiving home directory 
field, supplied by argument 1, is placed in SB4; 
if this argument is omitted, $B4 is assumed to 
contain the correct address. 


2. On return, SR1 contains one of the following 
status codes: 


0000 -— No error | 
0817 - Memory access violation 
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On return, SB4 contains the address of the 
receiving field. 


Example: 
In this example, the pathname of the initial working 


directory of the calling task group is stored in the 45- 
character field labeled DEF WD. 


SHDIR !DEF WD 
DEF WD RESV 22,0 
DC 0 
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( INPUT/OUTPUT REQUEST BLOCK 


INPUT/OUTPUT REQUEST BLOCK 

Macro Call Name: SIORB 

Function Code: None 

Equivalent Command: None 
Generates an input/output request block (IORB). The length 
of the IORB is eight or nine words in SAF (Short address 
form), and ten to twelve words in LAF (long address form). 


FORMAT: 


[label] SIORB [logical resource number], 
| [issuing task suspension option], 


{ 
% Or 
[issuing task termination option], 
[buffer address], 
[buffer byte alignment], 
[buffer range] 
ARGUMENT DESCRIPTION: 
logical resource number 
A value from 0 through 252 specifying the LRN of the 
device involved in the request. The value specified 
must be that of a system LRN. If this argument is 
omitted, the left byte of the I CTl word (see 
Appendix A) is set to Zero. 
issuing task suspension option 
One of the following values is specified to indicate 
whether the requesting task is to be suspended until 
the completion of the request: 
; WAIT - Suspend the issuing task until the request is 
( complete (set the w-bit to zero) 
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NWAIT - Do not suspend the issuing task (set the w-bit 
to l) 


If this argument is omitted, the value NWAIT is 
assumed. 


If WAIT is specified, argument 3 must be omitted. 


issuing task termination option 


One of the following values is specified to indicate 
the action to be taken upon the completion of the 
request. 


SM=aa —- Do not suspend the isSuing task; release 
(V-op) the semaphore identified by aa (two 


ASCII characters), when requested task is 
completed. 


RB=label - Do not suspend the issuing task; issue a 
request for the request block identified by 
label, when requested task is completed. 


If this argument is omitted (or argument 2 is WAIT), 
the generated IORB contains no termination option. 


buffer address 


Address of a buffer area to be used for input/output 
transfers involving the specified device. If this 
argument is omitted, the buffer address field in the 
generated IORB is initialized to Zeros. 


buffer byte alignment 


A value specifying the beginning byte of the buffer, 
as follows: 


R —- Buffer begins in right byte of word address 
specified by argument 4 


L - Buffer begins in left byte of word address 
specified by argument 4 


If this argument is omitted, a value of L is assumed. 


buffer range 


A value specifying the length, in bytes, of the buf- 
fer. If this argument is omitted, the generated 
IORB's range value is initialized to zero. 
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FUNCTION DESCRIPTION: 


The input/output reguest block (IORB) is used as the stan- 
dard means of requesting a physical I/O service. The IORB 
contains an LRN which identifies the I/O device being 
addressed. The IORB also identifies the location and size 
of the buffer to be used for physical I/O transfers as well 
as the specific function requested. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information 
about SAF/LAF independent code. 


Example: 


In this example, the $IORB macro call generates a standard 
IORB having an LRN of 0, a WAIT status indicating that the 
requesting task will wait for I/O completion, and a label 

(DBUF) that gives the location of the 140-byte buffer area. 


CON IO STORB O, WAIT,, DBUF,, 140 
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INPUT/OUTPUT REQUEST 
BLOCK OFFSETS 


INPUT /OUTPUT REQUEST BLOCK OFFSETS 

Macro Call Name: SIORBD 

Counterpart: SIORB (See "Input/Output Request Block") 
Generated Label Prefixes: 


I RRB/I_ SEM 

ITORB label offset 0 
I cTl 
lL -CT2 
I ADR 
I RNG 
I DVS 
I_RSR 
IosF 


See Appendix A for the format of the input/output request 
block. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information 
about SAF/LAF independent code. 
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OR, 


INTERNAL DATE/TIME, CONVERT TO 


INTERNAL DATE/TIME, CONVERT TO 


Led 


Macro Call Name: SINDTM 


Function Code: 05/07 


Equivalent Command: None 


Convert the external format date/time value to an internal 
format date/time value. 


FORMAT : 


[label] 


SINDTM [location of address of external date/time], 
[location of address of receiving field], 
[location of size of external date/time] 


ARGUMENT DESCRIPTION: 


location of address of external date/time 


Any address form valid for an address register; pro- 
vides the address of a field containing an external 
date/time value. This value must be in the format 
returned by the convert to external date/time macro 
call. 


location of address of receiving field 


Any address form valid for an address register; pro- 
vides the address of a 3-word field into which the 
system places the internal format date/time value. 


location of size of external date/time 


Any address form valid for a data register; provides 
the size of the external date/time value identified by 
argument 1. The size must be less than or equal to 22 
bytes. If this argument is omitted, the size is set 
to 20 bytes (tenth of a second resolution). 


she size must be such that the date/time value does 
not end with the characters : (colon) or . (period). 


5-169 CBO08 


FUNCTION DESCRIPTION: 


This call converts an external date/time value (as supplied 
by the convert to external date/time macro call) to internal 
format (as supplied by the get date/time macro call). The 
internal date/time value appears in the receiving field as a 
binary count of the milliseconds that have elapsed from 

1 January 1901 at 00:00:00.000 hours. 


NOTES: l. 


The address of the external date/time value sup- 
plied by argument 1 is placed in $B4; if this 
argument is omitted, $B4 is assumed to contain 
the correct external value. 


The internal date/time value returned is loaded 
into SR2, SR6, and S$R7, and is placed in the 
receiving field specified by argument 2. If 
argument 2 is omitted, or is =SR7, the internal 
date/time value is returned only in $R2, SR6, 
and SR7. 


The size of the external date/time value sup- 
plied by argument 3 is placed in S$R5. If this 
argument is =SR5, it is assumed that $R5 con- 
tains the correct size. If this argument is 
omitted, S$R5 is set to a value of 20 (tenth of a 


second resolution). 


On return, SR1, $R2, SR6, SR7, and $B4 contain 
the following information: 


SR1 - Return status; one of the following: 
0000 - No error 
0407 - Invalid external date/time value 
O40A - Invalid input field address 


SR2, SR6, SR7 - Generated internal date/time 
value 


SB4 - Address of supplied external date/time 
value 
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Example: 


In this example, the SGDTM macro call is used to get the 
current date/time, in internal format, leaving it in regis- 
ters S$R2, SR6, and S$R7. The SEXDTM macro call is then used 
to convert this internal format to an external format, 
replacing the date portion (first 10 characters) of the 
field labeled TODAY. The TODAY field now contains the 
external format date/time for 0800 hours of today. The 
SINDTM macro call then converts this date/time value back to 
an internal format contained in $R2, S$R6, and S$R7. One day 
(86,400,000 milliseconds) is then added to this internal 
date/time giving the internal date/time for 0800 hours 
tomorrow, which is stored in the 3-word field labeled 
MORROW. The addition is programmed with the assumption that 
the central processor does not have the add integer double 
instruction. 


* 


z GET THE CURRENT DATE/TIME VALUE. 
* 


SGDTM 
* 


= CONVERT IT TO AN EXTERNAL FORMAT DATE. 


% 


SEXTDT , !TODAY,=10 


* 
= NOW CONVERT THE EXTERNAL DATE/TIME 
‘s BACK TO THE INTERNAL FORMAT. 

* 


SINDTM I! TODAY, ,=15 
* ADD IN ONE DAY. 


ADD §R7,A DAY+1 


CAD =SR6 

CAD =SR2 

ADD SR6,A DAY 
CAD =SR2 


+ 


NOW STORE THE RESULT. 


STR  $R2,MORROW 
SDI  MORROW+1 


TODAY TEXT "YYYY/MM/DD 0800" 
A DAY DC 86400000B(31,0) 
MORROW RESV 3,0 


5-171 CBO8 


MESSAGE GROUP, ACCEPT 


MESSAGE GROUP, ACCEPT 
Macro Call Name: SMACPT 
Function Code: 15/01 
Equivalent Command: None 


Establish a message connection, through a mailbox, between 
an initiator's task group and the acceptor (calling) task 
group issuing this SMACPT macro call. 


FORMAT : 


[label] SMACPT [location of MGIRB address] 
ARGUMENT DESCRIPTION: 
location of MGIRB address 


Any address form valid for a data register; provides 
the address of the message group initialization 
request block (MGIRB), which must have been previously 
generated. 


FUNCTION DESCRIPTION: 


The acceptor task group issues this macro call in order to 
accept a connection request initiated (with a SMINIT macro 
call) by the initiator task group. The SMACPT macro call 

(1) indicates that the acceptor task group wishes to receive 
a message from a named mailbox (message queue), and (2) 
opens the receive function of the message facility. (See 
the System Concepts manual for a discussion about the mes- 
sage facility. 


NOTES: 1. Mailboxes must have been created before the 
macro call is issued. (See the create mailbox 
(CMBX) command in the Commands manual.) Refer- 
ence to mailbox fields when no mailbox has been 
created results in an error return. 
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( 2. The system places the address of the MGIRB in 

3 SB4. If the argument is omitted, the system 
assumes that S$B4 contains a pointer to the 
MGIRB. 


3. Before the SMACPT macro call is executed, the 
user muSt generate the MGIRB (see Table A-8) 
with the argument values shown in Table 5-2. 


Table 5-2. MGIRB Argument Values for SMACPT Macro Call 


Field in 
Argument Name and Description MGIRB Argument Value 


RARE ve A ae a a RC AIEEE (SARL te eae SR ERNST, EAR SNE a GRASP A et Bs INE RS SRN Se eS Ne ESTE 
SynchronousS/asynchronous 
indicator 


MI MAJ O —- Synchronous; task 

(bit 9) waits until all 
Specified message 
group conditions are 
met before macro 
call is executed. 


Indicates whether macro 
call execution is to be 


Synchronous or 
asynchronous. 


Asynchronous; task 
does other process- 
ing while checking 
whether the message 
group conditions 
have been met. 


Reserved for future uSe. MI MPD Must be OOO]. 


acceptor identification As shown below. 


Che, 


Describes the following 
characteristics of the 
acceptor at a mailbox that 
is the destination of the 
message group: 


address type: a Must be hexadecimal Ol. 


Specifies that this is 
an acceptor's address. 


Reserved for future use. iz Must be 0. 


Reserved for future uSe. a Must be 0. 


acceptor mailbox ~ Must be from 1 to 12 
ASCII characters, blank- 
filled, left justified. 
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At successful macro execution, the system 
returns the following MGIRB output argument 
values: 


message group identifier: 
MG MGI field: is the message group 
identifier of the "accepted" message group. 
A valid identifier is returned for all 
requests even when a message group is not 
available. 

initiator identification: 
Designates the following characteristics of 
the initiator at a mailbox from which the 
acceptor will accept the message group: 


address type: 


MI ADT field (bits 0 through 7), indi- 
cates an initiator address. 


mailbox name: 
MI MBI field; is the name (from 1 to 
12 ASCII characters, blank-filled, 
left justified) of the mailbox 
designated by the initiator task group 
as the initiator mailbox. 


On return, SR1 contains the following status 
codes: 


OO00 - No error 


0C23 - Invalid message path description 
identifier | 


0C25 - Acceptor mailbox may not be accessed by 
initiator 


0C26 - Acceptor mailbox not known 
0C62 - Normal message group termination 
On return, register S$B4 will point to the 


application's MGIRB, which is updated according 
to the specifications in the macro call. 
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te, 


MESSAGE GROUP CONTROL 
REQUEST BLOCK 


MESSAGE GROUP CONTROL REQUEST BLOCK 


Macro Call Name: SMGCRB 
Function Code: None 
Equivalent Command: None 


Depending on the arguments supplied in the call, does one of 
the following: 


o Builds a message group control request block (MGCRB) of 
24 words (for SAF) and 28 words (for LAF) that contains 
default values for all fields not explicitly specified in 
the call. See Table A-7 in Appendix A. 


o Generates instructions to alter the partial contents of 
an existing MGCRB. 


FORMAT: 
[label] SMGCRB ,[arguments] 
ARGUMENT DESCRIPTION: 
There are three types of arguments for this macro call: 
o Keyword only (i.e., RESV). 


Oo Keyword with expression (expresSion is a user-selected 
variable whose literal value is used by the system). 


Oo Keyword with option (option is a prescribed ASCII string 
that is interpreted by the system). 


The keyword-only argument RESV generates an MGCRB. When the 
macro call is issued with RESV as its only argument, an 
MGCRB is built with system-assigned default values. When 
RESV is specified with other arguments, all entries in the 
MGCRB that are not specifically changed by other arguments 
are defaulted. 
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Omitting the RESV argument generates executable code to 
modify an existing MGCRB, in which case the keyword with 
expression argument ADR=address is used to specify the 
address of the MGCRB to be changed. When ADR=address is 
omitted, the system assumes that register $B4 points to that 
MGCRB. The argument ADR=address is not used in building a 
new MGCRB, i.e., when RESV is specified, the system ignores 
any ADR=address argument. 


The other keyword-only arguments are WAIT and NWAIT, which 
are described in Table 5-3 below. 


The first argument position is reserved for system use, and 
must be specified by the user as a comma. The second and 
third arguments are positional, and when omitted, each must 
be replaced by a comma. 


Table 5-3 describes the arguments for the SMGCRB macro call, 
and indicates the fields in the MGCRB into which the system 
inserts the argument values. 


Table 5-3. Argument Values for SMGCRB Macro Call 


Argument Ke yword Field in 
PoSition Keyword | Value Argument Description MGCRB 


None None Reserved by system, must 
be a comma. 


Issuing task Suspension MC MAJ 
option: 


Suspend the issuing task 
until the request is 
completed (set W-bit 
(wait) to 0). 


NWA IT 
(default) 


Do not suspend the 
issuing task (set W-bit 
to l). 


5-176 CBO08 


Table 5-3 (cont). Argument Values for SMGCRB Macro Call 


Argument Keyword Field in 
Position Ke ywo rd Value Argument Description MGC RB 


Keyword with expression 


Issuing task termination’ N/A 
option: 


aa When requested task is 
completed, do not 
suspend issuing task; 
release the semaphore 
identified by the two 
ASCII characters aa. 


label When requested task is 
complete, do not suspend 
the issuing task; issue 
a request for the 
request block identified 
by label. 


Any ADR= address When existing MGCRB is N/A 
to be changed (RESV 
omitted), specifies 
address of MGCRB to be 
changed. 


Any BUF= buffer Address of the buffer 
address location in the task 
where sent or received 
(default] record is to be placed. 
is 0) 


Any RANGE= number Length, in bytes of the 
of bytes! buffer. 


(default 
is 0) 
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Table 5-3 (cont). se Values for SMGCRB Macro Call 


Argument Keyword Field in 
ee Leer a bcc, ee ENE Pesce On. Description ee 


F Ss~*~s—s—SCKeyword with option =—ss—~s—sSY fT sSs—~—~—s—CReyword with option sis option 


Buffer byte alignment: MC OPT 


Buffer begins in right- 
most byte of address 
specified by BUF= 
argument. 


L 
(default 
| pat ae) 


Buffer begins in left- 
most byte of address 
specified by BUF= 
argument. 


: : 
“a 


a 
When WAIT is specified, argument 3 must be omitted. 


Wait test indicator (for 
SMRECV only): 


MC_WTI 


WAIT Do not process request 


until data is available. 


Return error Status when 
there is no data 
available. 


DENY 
(default 
value) 


Enclosure level that 
delimits send or receive 
message unit. 


MC_LVL 


EOR | End-o f-record. 


EOQ 
(default 
value) 


End-of-quarantine-unit. 


EOM End-o f-message. 


b 
When this argument is omitted, or argument 3 is WAIT, the 

generated MGCRB contains no termination option. In that case, 
the user must issue a SWAIT, SWAITL, or STEST macro call. 
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FUNCTION DESCRIPTION: 


The message group control request block (MGCRB) is used for 
communication between task groups, and is the means for 
passing arguments among task groups in connection with the 
message group send (SMSEND) and message group receive 
(SMRECV) macro calls of the message facility. This macro 
call makes it possible to modify an existing MGCRB by 
generating executable instructions that use registers SR6, 
SR7, and $B5 (as appropriate). The modifying process always 
uses SB4 to point to the MGCRB. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 
independent code. 
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MESSAGE GROUP CONTROL 
REQUEST BLOCK OFFSETS 


MESSAGE GROUP CONTROL REQUEST BLOCK OFFSETS 


Macro Call Name: SMGCRT 


Generated Label Prefixes: 


trol 


MC_OS 
MC MAJ 


MC OPT 


MC BUF 
MC BSZ 


MC DVS/MC_REC 


MC RSR 


MC MRU/MC_ WTI 


MC EXT 


MC FNC/MC_REV 


MC MGI 
MC LVL 
MC PCI 
MC VDP 
MC _TGI 
MC TSK 
MC NPI 


Appendix A describes the contents of the message group con- 
request block (MGCRB). 


NOTE: 


This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for information about SAF/LAF 


independent code. 
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4 


MESSAGE GROUP, COUNT 


MESSAGE GROUP, COUNT 


Macro Call Name: SMCMG 
Function Code: 15/07 
Equivalent Command: None 


Provide a count of the number of completed message groups, 
not yet "accepted" by previous SMACPT macro calls, that are 
available for processing by subsequent SMACPT macro calls. 


FORMAT: 

[label] SMCMG [location of MGIRB address] 
ARGUMENT DESCRIPTION: 
location of MGIRB address 


Any address form valid for a data register; provides 
the address of the message group initialization 
request block (MGIRB), which must have been previously 
created. 


FUNCTION DESCRIPTION: 


The sending or receiving task group may issue this macro 
call to ascertain the number of completed groups currently 
in the mailbox not yet "accepted" by earlier SMACPT macro 
calls, and available to subsequent SMACPT macro calls. The 
mailbox is described in the MGIRB for this macro call (see 
Table 5-4 below). 


NOTES: 1. Referenced mailboxes must have been created 
before this macro call is issued. (See the 
create mailbox (CMBX) command in the Commands 
manual.) References to mailbox fields when no 
mailbox has been created results in an error 
return. 
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2. The system places the address of the MGIRB in 
register S$B4. If this argument is omitted, the 
System assumes that $B4 contains a pointer to 
the MGIRB. 


3. Before the macro call is executed, the user must 
generate the MGIRB (see Table A-8) with the 
argument values Shown in Table 5-4). 


Table 5-4. MGIRB Argument Values for SMCMG Macro Call 


Field | 
Argument Name and Description | in MGIRB Argument Value 


Ssynchronous/asynchronous MI MAJ | 0 - Synchronous; task 


waits until all 
As shown 
| below 


Indicates whether macro 
call execution is to be 
synchronous or 
asynchronous 


specified message 

group conditions are 
met before the macro 
call is executed. 


1 - Asynchronous; task 
continues with other 
processing while 
checking whether the 
message group condi- 

tions have been met. 


acceptor identification As shown below. 


Describes the following 
characteristics of the 
acceptor at a mailbox 

that contains the message 
groups. 


address type: MI ADT Must be hexadecimal Ol. 
Specifies that this is an] (bits 
acceptor's address 8-F) 


Reserved for future use. 


MI NWA Must be O. 
MI NDA Must be 0O. 


MI_MBA Must be from 1 to 12 
ASCII characters, blank- 
filled, left justified. | 
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Reserved for future use. 


acceptor mailbox name 


( 4. At successful macro execution, MI CNT will con- 
: tain the count of "unaccepted" completed message 
groups remaining in the mailbox. 


5. On return, SR1 contains the following return 
status codes: 


OO000 -—- No error 


OCO2 - Invalid message group identification 
0C03 - Abnormal termination received 
O0C09 - Invalid enclosure level specified 


0C25 - Acceptor mailbox may not be accessed 
by the initiator 


0C26 - Acceptor mailbox or acceptor mailbox 
node not known 


0C 34 User-coded reason for abnormal message 
through - group termination 
0C44 


OC62 - Normal message group termination 
6. On return, register S$B4 will point to the 


application's MGIRB, which is updated according 
to the specifications in the macro call. 
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MESSAGE GROUP INITIALIZATION 
REQUEST BLOCK 


MESSAGE GROUP INITIALIZATION REQUEST BLOCK 


Macro Call Name: SMGIRB 


Function Code: None 


Equivalent COmmand: None 


Depending on the arguments Supplied in the call, does one of 
the following: 


fe) 


Builds a message group initialization request block 
(MGIRB) of 42 words (for SAF) and 46 words (for LAF) that 
contains default values for all fields not explicitly 
specified in the call. See Table A-8 in Appendix A. 


Generates instructions to alter the partial contents of 
an existing MGIRB. 


When modifying an existing MGIRB, calls and expands the 
corresponding SMGIRT template macro call to provide 
labels for the MGIRB's fields. 


FORMAT : 


[label] SMGIRB ,[farguments] 


ARGUMENT DESCRIPTION: 


There are three types of arguments for this macro call: 


O 


1@) 


Keyword only (i.e., RESV). 


Keyword with expression (expression is a user-selected 
variable whose literal value is used by the system). 


Keyword with option (option is a prescribed ASCII string 
that is interpreted by the system). 
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The keyword-only argument RESV generates an MGIRB. When the 
macro call is issued with RESV as its only argument, an 
MGIRB is built with system-assigned default values. When 
RESV is specified with other arguments, all entries in the 
MGIRB that are not specifically changed by other arguments 
are defaulted. 


Omitting the RESV argument generates executable code to 
modify an existing MGIRB, in which case the keyword with 
expression argument ADR=address is used to specify the 
address of the MGIRB to be changed. When ADR=address is 
omitted, the system assumes that register $B4 points to that 
MGIRB. The argument ADR=address is not used in building a 
new MGIRB, i.e., when RESV is specified, the system ignores 
any ADR=address argument. 


The other keyword-only arguments are WAIT and NWAIT, which 
are described in Table 5-5 below. 


The first argument position is reserved for system use, and 
must be specified by the user as a comma. The Second and 
third arguments are positional, and when omitted, each must 
be replaced by a comma. | 


Table 5-5 describes the arguments for the SMGIRB macro call, 
and indicates the fields in the MGIRB into which the system 
inserts the argument values. 


Table 5-5. Argument Values for SMGIRB Macro Call 


Argument Keyword 
Position Keyword Value Argument Description 


Keyword only 


] None None Reserved by system, must N/A 
be a comma. 


5 | 
a 
WAIT None 


Issuing task suspension MI_MAJ 
option: 


Suspend the issuing task 
until the request is 
completed (set W-bit 
(wait) to 0). 


NWA IT None Do not suspend the 
issuing task (set W-bit 


to 1). 
RESV Generates the MGIRB. 
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(default) 


Table 5-5 (cont). Argument Values for SMGIRB Macro Call 


Argument Keyword Field in 
Position Ke yword Value Argument Description MGIRB 


Keyword with expression 


b 
Issuing task termination 
option: | 


aa When requested task is 
completed, do not suspend 
issuing task; release the 
semaphore identified by 

the two ASCII characters 


AA e 


label When requested task is 
complete, do not suspend 
the issuing task; issue a 
request for the request 
block identified by 


label. 


When existing MGIRB is to N/A 
be changed (RESV omit- 

ted), specifies address 
of MGIRB to be changed. 


Any ADR= address 


Any MB I= Initiator mailbox name: 
From 1 to 12 ANSII charactrs, 
blank-filled, left justified. 
Default is 12 blanks. 
Any MBA= Acceptor mailbox name. 
From 1 to 12 ANSII characters, 
blank-filled, left justified. 
Default is 12 blanks. 


a 
When WAIT is specified, argument 3 must be omitted. 


b 
When this argument is omitted, or argument 3 is WAIT, the 
generated MGIRB contains no termination option. In that case, 

the user must issue a SWAIT, SWAITL or STEST macro call. 
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FUNCTION DESCRIPTION: 


The message group initialization request block (MGIRB) is 
used for communication among task groups, and is the means 
for passing arguments among task groups in connection with 
the message group accept (SMACPT), message group initiate 
(SMINIT), and message group count (SMCMG) macro calls of the 
message facility. This macro call makes it possible to 
modify an existing MGIRB by generating executable instruc- 
tions that use registers $R6, S$R7, and $B5 (as appropriate). 
The modifying process always uses S$B4 to point to the MGIRB. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 
independent code. 
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MESSAGE GROUP INITIALIZATION 
REQUEST BLOCK OFFSETS 


MESSAGE GROUP INITIALIZATION REQUEST BLOCK OFFSETS 
Macro Call Name: SMGIRT 
Generated Label Prefixes: 


MI OS 

MI MAJ 

MI OPT 

MI BUF 

MI BSZ 

MI MPD 

MI RSR 

MI MDE/MI IOP 
MI-EXT ~— 
MI FNC/MI REV 
MI MGI 7 
MI PCM/MI_ADT 
MI NWI 

MI NDI 

MI MBI 

MI NWA 

MI NDA 

MI MBA 

MI QSZ 

MI CNT 

MI TGI 

MI TSK 

MI SIP 


Appendix A describes the contents of the message group 
initialization request block (MGIRB). 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for information about SAF/LAF 
independent code. 
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( MESSAGE GROUP, INITIATE 


MESSAGE GROUP, INITIATE 
Macro Call Name: SMINIT 
Function Code: 15/02 
Equivalent Command: None 


Initiate a message connection, through a previously created 
mailbox, between the initiating task group (initiator) and 
the accepting task group (acceptor). 


FORMAT: 
[label] SMINIT [location of MGIRB address] 


ARGUMENT DESCRIPTION: 


ba 


location of MGIRB address 


Any address form valid for a data register; provides 
the address of the mesSage group initialization 
request block (MGIRB), which must have been previously 
generated. 


FUNCTION DESCRIPTION: 


A task group that is to send a message (initiator task 
group) to another task group must issue the SMINIT macro 
call to open the send function of the message facility. 
(See the System Concepts manual for a discussion about the 
message facility.) The macro routine informs the system 
that a message connection is requested in order to send a 
message, and provides the name of the initiator's mailbox. 


NOTES: 1. Mailboxes must have been created before the 
macro call is issued. (See the create mailbox 
(CMBX) command in the Commands manual.) 


2. The system places the address of the MGIRB in 
SB4. If the argument is omitted, the system 
: assumes that $B4 contains a pointer to the 
( : MGIRB. 
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3. Before the SMINIT macro call is executed, the 
user must generate the MGIRB (see Table A-8) 
with the argument values shown in Table 5-6. 


Table 5-6. MGIRB Argument Values for SMINIT Macro Call 


Field in 
Argument Name and Description MGIRB Argument Value | 


SynchronousS/asynchronous O —- Synchronous; task 
indicator waits until all 
Specified message 
Indicates whether macro group conditions are 
call execution is to be met before the macro 
synchronous or call is executed. | 
asynchronous. 


1 - Asynchronous; task 
continues with other 
processing while , 
checking whether the] 
message group condi- 
tions have been met. 


Reserved for future use. MI MPD Must be OOO]. 


initiator identification As shown below. 


Must be hexadecimal l. 


Describes the following 
Characteristics of the 
initiator at a mailbox 
where the message group 
originates. 


address type 


Specifies that this is an 
initiator's address. 


Reserved for future use. 


MI NWI Must be 0O. 
MI NDI Must be 0. 


MI MBI Must be from 1 to 12 
ASCII characters, blank-| 
filled, left-justified. 


Reserved for: future use. 


initiator mailbox name 
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The SMINIT macro call is effective only for a 
one-way connection to another task group's mail- 
box. For the other task group to send messages, 
it must create its own initiator mailbox and 
issue its own SMINIT macro call. 


On successful macro execution, the system 
returns the message group identifier (MI MGI 
field) of the "initiated" message group. A 
valid identifier is returned for all requests. 


On return, S$R1 contains the following return 
status codes: 


0000 -—- No error 


0C23 - Invalid message-path-description 
identifier 


0C25 - Acceptor mailbox may not be accessed b 
initiator 


0C26 - Acceptor mailbox not known 


OC 34 User-coded reason for abnormal message 
through —- group 
0C44 


OC62 —- Normal message group termination 
On return, register $B4 will point to the 


application's MGIRB, which is updated according 
to the specifications in the macro call. 
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MESSAGE GROUP, RECEIVE 


MESSAGE GROUP, RECEIVE 
Macro Call Name: SMRECV 
Function 6iges- 15/03 
Equivalent Command: None 


Requests that this task group receive a message group via a 
named mailbox, from another task group, specifies how much 


message data is to be received, and detects when there is no 
more data to be received. 


FORMAT : 


[label] SMRECV [location of MGCRB address] 


ARGUMENT DESCRIPTION: 
location of MGCRB address 


Any address form valid for a data register; provides 
the address of the message group control request block 
(MGCRB), which must have been previously generated. 


FUNCTION DESCRIPTION: 


The task group that issued the SMACPT macro call to open the 
receive function of the message facility can issue one or 
more SMRECV macro calls in order to receive message data 
from the sending task group, via named mailboxes. The mes- 
Sage group identifier returned in the SMACPT macro call is 
used by the SMRECV macro call to identify the message groups 
of the sending and receiving task groups. A receive message 
can be any unit, not necessarily exactly as defined by the 
Sender. A portion of a message group cannot be received 
unless designated as a quarantine unit by the sender. The 
SMRECV macro call can request that the message be received 
in record sizes other than those with which it was sent. It 
can specify how much data is to be received in terms of 
numbers of bytes (range), and by "enclosure level" (see 
below). Every receive unit is an enclosure. The receiving 
task group can delimit the amount of received data as 
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end-of-quarantine-unit (see description of quarantine unit 
under the message, send (SMSEND) macro call) or as end-of- 
message. 


NOTES: 1. Mailboxes must have been created before this 
macro call is issued. (See the create mailbox 
(CMBX) command in the Commands manual.) 

2. The system places the address of the MGCRB in 
register $B4. If the argument is omitted, the 
system assumes that $B4 contains a pointer to 
the MGCRB. 

3. Before issuing the macro call, the user must 
generate the MGCRB (see Table A-7) with the 
argument values Shown in Table 5-7. 


Table 5-7. MGCRB Argument Values for $MRECV Macro Call 


Field in 
Argument Name and Description MGCRB Argument Values 


message group identifier MC_MGI Value returned in SMACPT 
macro call. 
MC_BUF 


MC_BSZ 
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Identifies the message 
group within whose 

enclosures the record is to 
be received. 


buffer area identifier Buffer pointer. 


Defines the location within 
the task where the received 
record is to be placed. 


range User-specified. 


Defines the maximum number 
of bytes to be placed into 
the buffer area in one 
execution of the macro 
call. When the specified 
range is exceeded, the 
transfer of message text is 
terminated. 


Table 5-7 (cont). MGCRB Argument Values for SMRECV Macro Call 


Field in 
Argument Name and Description MGCRB Argument Values 


requested enclosure level MC_LVL ASCII values: 


(bits l End-of-record, but 
0-7) not last record in 
Quarantine unit. 


Amount of data, in text 
units, that the receiving 
task group is to receive. 
When the buffer range is 
exceeded, text transfer 
terminates. 


End-o f-quarantine- 
unit. 


End-o f-message. 


the 


Terminate 
request. 


wait test indicator 


Specifies whether user 
waits for data, even if 
none now available; or 
whether request is 
terminated when there is no 
data. 


1 - Wait for data to 
become available. 


Synchronous/asynchronous | 
indicator 


Synchronous; task 
waits until all 
specified message 
group conditions are 
met before the macro 
call is executed. 


Indicates whether macro 
call execution is to be 
synchronous or 

asynchronous. 


1 - Asynchronous; task 
continues with other 
processing while 
checking whether the 
message group condi- 

tions have been met. 


4. After successful receipt of a complete message 


(i.e., value of detected enclosure level in 

bits 8-F in MC_LVL is ASCII 5) the receiving 
task group must issue a message group terminate 
(SMTMG) to terminate the message group. (See 
“Message Group, Terminate" later in this section 
for a discussion of normal and abnormal | 
termination.) | 
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5. At successful macro execution, the system 
returns the following MGCRB output argument 
values: 


test length (range): 


MC RSR field, reports the number of bytes 
of text not transferred into the buffer 
area. When a record has no text asSociated 
with it, the value will equal buffer size. 


detected user enclosure level: 


MC LVL field (bits 8-F), reports the 
enclosure level detected at end of the 
transfer. Possible values (ASCII): 


- No enclosure detected 
- End-of-record 

- End-o f-quarantine-unit 
- End-o f-message 
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6. On return, register $R1 contains the following 
status codes: 


COO0O0 - No error 


OC02 - Invalid message group identifier 

0CO3 - Abnormal termination received 

0C09 - Invalid enclosure level specified 

OC16 - Message quarantine unit exceeded 
capacity 

0C33 - Invalid user-coded abnormal 


termination 


0C 34 User-coded reason for abnormal message 
through - group termination 
0c 44 


OC62 - Normal message group termination 
0C64 - Terminate request rejected 
7. On return, register SB4 will point to the 


application's MGCRB, which is updated according 
to the specifications in the macro call. 
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MESSAGE GROUP RECOVERY 
REQUEST BLOCK 


MESSAGE GROUP RECOVERY REQUEST BLOCK 


Macro Call Name: SMGRRB 


Function Code: None 


Equivalent Command: None 


Depending on the arguments supplied in the call, does one of 
the following: 


oO 


Builds a message group recovery request block (MGRRB) of 
24 words (for SAF) and 27 words (for LAF) that contains 
default values for all fields not explicitly specified in 
the call. See Table A-9 in Appendix A. 


Generates instructions to alter the partial contents of 
an existing MGRRB. 


When modifying an existing MGRRB, calls and expands the 
corresponding SMGRRT template macro call to provide 
labels for the MGRRB's fields. 


FORMAT : 


[label] SMGRRB , [arguments] 


ARGUMENT DESCRIPTION: 


There are three types of arguments for this macro call: 


\@) 


Oo 


Keyword only (i.e., RESV). 


Keyword with expression (expression is a user-selected 
variable whose literal value is used by the system). 


Keyword with option (option is a prescribed ASCII string 
that is interpreted by the system). 
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The keyword-only argument RESV generates an MGRRB. When the 
macro call is issued with RESV as its only argument, an 
MGRRB is built with system-assigned default values. When 
RESV is specified with other arguments, all entries in the 
MGRRB that are not specifically changed by other arguments 
are defaulted. 


Omitting the RESV argument generates executable code to 
modify an existing MGRRB in which case the keyword with 
expression argument ADR=address is used to specify the 
address of the MGRRB to be changed. When ADR=address is 
omitted, the system assumes that register $B4 points to that 
MGRRB. The argument ADR=address is not used in building a 
new MGRRB, i.e., when RESV is specified, the system ignores 
any ADR=address argument. 


The other keyword-only arguments are WAIT and NWAIT, which 
are described in Table 5-8 below. 


The first argument position is reserved for system use, and 
must be specified by the user as a comma. The second and 
third arguments are poSitional, and when omitted, each must 
be replaced by comma. 


Table 5-8 describes the arguments for the SMGRRB macro call, 
and indicates the fields in the MGRRB into which the system 
inserts the argument values. 


Table 5-8. Argument Values for SMGRRB Macro Call 


Argument Ke ywo rd Field in 
Position Keyword Value Argument Description MGRRB 


Keyword only 


None None Reserved by system, must 
be a comma. 


Issuing task suspension MR_ MAJ 
option: 


Suspend the issuing task 
until the request is 
completed (set W-bit 
(wait) to 0). 


NWAIT 
(default) 


Do not Suspend the 
issuing task. (Set W-bit 
bit to l.) 


RES V Generates the MGRRB. 
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Table 5 -8 (cont). Argument Values for SMGRRB Macro Call 


Argument Keyword Field in 
Position Wa dk eee see Argument Pree ee MGRRB 


"Renore:: with expression 
il 
a 


MR_RSN | 


b 
When this argument is omitted, or argument 3 is WAIT, the 

generated MGRRB contains no termination option. In that case, 

the user must issue a SWAIT, SWAITL, or STEST macro call. 


: : : b 
Issuing task termination 
option: 


When requested task is 
completed, do not suspend 
issuing task; release the 
semaphore identified by 
the two ASCII characters 
aa. 


When requested task is 
complete, do not suspend 
the issuing task; issue a 
request for the request 
block identified by 
label. 


When existing MGRRB is to 
be changed (RESV omit- 
ted), specifies address 
of MGRRB to be changed. 


address 


QO, or 
34 
through | 
44 


Message group termination 
code: 


0 - Indicates normal 
termination of this 
message group. 


34 through 44 - User- 
coded reason for 
abnormal termination. 


a 
When WAIT is specified, argument 3 must be omitted. 
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FUNCTION DESCRIPTION: 


The message group recovery request block is used for com- 
munication between task groups, and is the means for passing 
arguments among task groups in connection with the message 
group terminate (SMTMG) macro call of the message facility. 
This macro call makes it possible to modify an existing 
MGRRB by generating executable instructions that use regis- 
ters SR7 and $B5 (as appropriate). The modifying process 
always uses $B4 to point to the MGRRB. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 


independent code. 
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MESSAGE GROUP RECOVERY 
REQUEST BLOCK OFFSETS 


MESSAGE GROUP RECOVERY REQUEST BLOCK OFFSETS 


Sneed 
ener ae SR 7 OATES aL ARG ONAL rata yen Panta ae tn ta Page areas Ti | 


Macro Call Name: SMGRRT 


Generated Label Prefixes: 


MR_OS 

MR_ MAJ 

MR OPT 

MR BUF 

MR BSZ 

MR ITP 

MR RES 
MR_RSN 

MR EXT 
MR_FNC/MR_REV 
MR MGI 
MR CNC 

MR FMT 
MR_MRU 
MR_AMU 


Appendix A describes the contents of the meSSage group 
recovery request block (MGRRB). 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for information about SAF/LAF 
independent code. 
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SRER 


retest 


MESSAGE GROUP, SEND 


MESSAGE GROUP, SEND 


Eo 


Macro Call Name: SMSEND 
Function Code: 15/05 
Equivalent Command: None 


send a specified amount of message text from the initiator 
task group. Optionally, make this record and any previously 
Sent records visible to the receiver by declaring this mes- 
Sage text aS a quarantine unit. 


FORMAT: 

[label] SMSEND [location of MGCRB address] 
ARGUMENT DESCRIPTION: 
location of MGCRB address 


Any address form valid for a data register; provides 
the address of the message group control request block 
(MGCRB) , which must have been previously generated. 


FUNCTION DESCRIPTION: 


The task group that issued a SMINIT macro call to initiate 
the message connection, issues one or more SMSEND macro 
calls to send message data via that connection. A task 
group sending a message to another task group sends through 
a named mailbox. The message group identifier returned in 
the SMINIT macro call is used by the SMSEND macro call to 
identify the message group of the task group that initiated 
it. A message is one or more records. Each SMSEND sends 
one record, which is the baSic unit of data exchange. Each 
transmission is a buffer of data, which must point to the 
MGCRB that describes the buffer. Only when designated by 
the sender as a “quarantine unit," iS a sender's record or 
group of records interpreted at the destination (i.e., is 
visible). 
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Every send unit is an enclosure. The last or intermediate 
records in the message are identified by an enclosure level 
which delimits sent data as end-of-record, end-of- 
quarantine-unit, or end-of-message. End-of-message implies 
the end-of-quarantine-unit; end-of-quarantine-unit implies 
end-of-record. 


NOTES: 1. Mailboxes must have been created before this 
macro call is issued. (See the create mailbox 
command (CMBX) in the Commands manual.) 

2. The system places the address of the MGCRB in 
register S$B4. If the argument is omitted, the 
system assumes that S$B4 contains a pointer to 
the MGCRB. 

3. Before issuing the SMSEND macro call, the user 
must generate the MGCRB (see Table A-7) with the 
argument values shown in Table 5-9. 


Table 5-9. MGCRB Argument Values for SMSEND Macro Call 


Field in 
Argument Name and Description Name and Description L 2 MGCRS | Argument Value 


Synchronous/asynchronous MC MAJ 0 - Synchronous; task 
indicator (bit 9) waits until all 
Specified message 
Indicates whether macro group conditions are 
call execution is to be met before the macro 
synchronous or call is executed. 
asynchronous 
1 - Asynchronous; task 
continues with other 
processing while 
checking whether the 
| message group condi- 
tions: have been met. 


message group identifier MC MGI Value returned in SMINIT 
macro call. 
Identifies the message 
group within whose 
enclosure the record is to 
be sent 
buffer area identifier MC_BUF 

Defines the location 
within the task where the 
message text to be sent is 
located. 
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Buffer pointer. 


Table 5-9 (cont). MGCRB Argument Values for SMSEND Macro Call 


Field in 
Argument Name and Description MGCRB Argument Value 


user-requested enclosure MC LVL ASCII values: 
level a 
1 - End-of-record, but 
Defines the unit of text (bits not last record in a 
i.e., how much data, is 0-7) quarantine unit. 
contained in an 
"enclosure level." 2 - End-of-quarantine 
unit. 


5 - End-of-message. 


range | User-specified. 


Indicates the number of 
bytes of message text to be 
sent from the buffer area. 
A zero value indicates no 
text is to be sent; even 
then the other argument 
values are examined and a 
record enclosure is opened 
if not already open. 


4. To complete sending a message group, the sending 
task group must terminate the message group by 
either: 


o Specifying an ASCII 5 (end-of-message) 
enclosure level in MC _LVL of the MGCRB (see 
Table 5-9) supplied on an SMSEND macro call, 
or 


o Issuing the macro call message group termi- 
nate (SMTMG), with the value 0 in MR CNC of 
the MGRRB. (See "Message Group, Terminate" 
later in this section for a discusSion of 
normal and abnormal termination.) 


5. On return, register SRl contains the following 
return status codes: 


0000 - No error 
OCO2 - Invalid message group identification 


0C03 - Abnormal termination received 
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OC09 - Invalid enclosure level specified 


0C16 - Message/quarantine unit exceeded 
capacity 
0C 34 User-coded reason for abnormal message 
through - group termination 
0c44 
0C62 - Normal message group termination 


On return, S$B4 will point to the application's 
MGCRB, which is updated according to the 
specification in the macro call. 
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MESSAGE GROUP, TERMINATE 


MESSAGE GROUP, TERMINATE 
Macro Call Name: SMTMG 
Function Code: 15/04 
Equivalent Command: None 
Terminates a message group, either normally or abnormally. 
FORMAT : 
[label] SMIMG [location of MGRRB address] 
ARGUMENT DESCRIPTION: 
location of MGRRB address 


Any address form valid for a data register; provides 
the address of the message group recovery request 
block (MGRRB), which must have been previously 
generated. 


FUNCTION DESCRIPTION: 


This macro call, issued by a sending or receiving task 
group, causes normal or abnormal termination of a message 
group. A sending task group, after normal transmission of a 
message, must terminate the message group with either a 
SMSEND macro call that specifies an end-of-message enclosure 
level (5 in MC _ LVL of the MGCRB), or with a SMTMG macro call 
having a termination value of 0 in bits 0 through 7 of 
MR_RSN (see Table 5-10 below). The sending task group can 
Specify abnormal termination of the message group by 
inserting a uSer-coded value from 34 through 44 in bits 0-7 
of MR _RSN. This code informs the receiving task group of 
the reason for abnormal termination. 


NOTE: When a receiving task group terminates a mesSage 
group abnormally before the sending task group does, 
the sending task group will receive an 0C34 through 
0C44 error return on his next SMSEND macro call. At 
that point the sending task group can issue only a 
SMTMG macro call for normal termination. 
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A receiving task group, after issuing a SMACPT macro call 
and SMRECV macro call(s), and after receiving complete mes- 
Sage data (detected user enclosure level 5 in MC LVL), will 
receive a return status of 0000 in S$Rl. The receiving task 
group must then issue a SMTMG macro call to terminate the 
message group. When the receiving task group wants to ter- 
minate the message group before receiving the last completed 
data, it requests abnormal termination by specifying a user- 
coded termination value from 34 through 44 in bits 0 through 
7 of MR_RSN in a SMTMG macro call (see Table 5-10 below). 
This causes the message group to be removed from the receiv- 
ing task group and any remaining data to be purged. The 
sending task group, if still active, will receive the same 
return Status code (from 34 through 44) in SR1 when it next 
issues a SMSEND macro call. 


NOTES: 1. The system places the address of the MGRRB in 
register $B4. If the argument is omitted, the 
system assumes that S$B4 contains a pointer to 
the MGRRB. 


2. Before issuing this macro call, the user must 
generate the MGRRB (see Table A-9) with the 
argument values shown in Table 5-10 below. 


3. When the message group is terminated, its mes- 
sage group identifier is available for reuse. 


4, On return, register $Rl1 contains the following 
Status codes: 


0000 -—- No error 
O0CO02 - Invalid message group identifier 


0C33 - Invalid user-coded abnormal 
termination 


0C 34 User-coded reason for abnormal message 
through - group termination 
0c 44 


OC62 —- Normal message group termination 
OC64 - Terminate request rejected 
5. On return, register $B4 will point to the 


application's MGRRB, which is updated according 
to the specifications in the macro call. 
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ARES. 


Table 5-10. MGRRB Argument Values for SMTMG Macro Call 


Field in 
Argument Name and Description MGRRB Argument Values 


SsynchronouS/asynchronous 
indicator 


message group identifier 


Identifies the message 
group to be terminated. 
This message group must 
have been identified in 
a SMINIT or SMACPT macro 
call by the task group 
issuing this macro call. 


termination type 


Specifies whether message 
termination is normal or 
abnormal. 


MR_ MAJ QO —- Synchronous; task 

(bit 9) waits until all 
Specified message 
group conditions are 
met before macro 
call is executed. 


Asynchronous; task 
does other process- 
ing while checking 
whether the message 
group conditions 
have been met. 


MR_MGI Value returned on SMINIT 
and SMACPT macro calls. 


Q - Indicates normal 
termination. 


Any value from 34 to 44 
indicates abnormal ter- 
mination, and issued in 
SRl as user-coded error 
codes. Any value other 
than 0 or from 34 
through 44 is transmit- 
ted as 33. 
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MODE IDENTIFICATION 


MODE IDENTIFICATION 

Macro Call Name: SMODID 
Function Code: 14/03 
Equivalent Command: User Mode 


Returns the mode component of the calling task group's user 
identification to a 3-character receiving field. 


FORMAT: 


[label] SMODID [location of mode id field address] 
ARGUMENT DESCRIPTION: 
location of mode id field address 


Any address form valid for an address register; pro- 
vides the address of a 3-character, aligned, nonvary- 
ing field into which the system will place the mode 
component of the user identification associated with 
the issuing task group. 


FUNCTION DESCRIPTION: 


This call returns the mode component of the task group's 
user identification to a field in the issuing task. The 
mode identification returned is that entered as part of the 
LOGIN command that established the user as a primary or 
secondary user of this task group. See the Commands manual 
for details. 


The entire user id is returned by the user identification 
(SUSRID) macro call. . 


NOTES: 1. The address of the receiving mode id field, sSup- 
plied by argument 1, is placed in $B4; if this 
argument is omitted, $B4 is assumed to contain 
the address of the receiving mode id field. 
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2. On return, SR1 contains one of the following 
status codes: 


O0O00 - No error 
O817 - Memory access violation 


3. On return, $B4 contains the address of the 
receiving field. 


Example: 


In this example, SB4 is loaded with the address (MODFL) of a 
3-character field and the SMODID macro call is issued to 
place the mode identification of the task group in that 
field. 


MODFL RESV 3,0 
LAB SB 4,MODFL 
SMODID 
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NEW PROCESS 


NEW PROCESS 
Macro ait ave: SN PROC 
Function Code: 0OD/0B 
Equivalent Command: New Process (NPROC) 
Terminate the current task group request and restart the 


task group request with the same parameters as the original 
invocation of the task group for this request. 


FORMAT : 
[label] SNPROC 
ARGUMENT DESCRIPTION: 
There are no arguments for this macro call. 


FUNCTION DESCRIPTION: 


This call terminates the current request for the issuing 
task group, then restarts the request using the same param- 
eters as in the original request. 


Example: 


In this example, the SNPROC macro call is used to terminate 
and restart the task group request. 


AGA IN SN PROC 
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NEW USER INPUT 


NEW USER INPUT 

Macro Call Name: SNUIN 
Function Code: 08/04 
Equivalent Command: None 


Redefine, reset, or set the user-in file for the issuing 
task. The user-in file can be redefined by a new pathname, 
reset to the initial user-in file, or set to the file cur- 
rently defined as the command-in file. The action taken 
applies only to the task that issues the macro call. 


FORMAT: 


[label] SNUIN [location of pathname address] 


ARGUMENT DESCRIPTION: 
location of pathname address 


Any address form valid for an address register; pro- 
vides the pathname of the file that is to be used as 
the new user-in file for the issuing task. If SCIN is 
Specified for this argument, the file currently 
defined as the task's command-in file is also used as 
the new user-in file. If this argument is omitted, 
the file defined by the request group (SRQGRP) macro 
call as the user-in file for tasks in this task group 
is again used for this task. 


FUNCTION DESCRIPTION: 


This call allows the issuing task to uSe another file as the 
user-in file. 


If a pathname is specified in the macro call, input will be 
read from the file identified by the pathname. 


If SCIN is specified as argument 1, the file that is cur- 
rently the task's command-in file will be used as the source 
of input for the task. 
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If the call is written without an argument, the user-in file 
is identified as the initial user-in file for this task. 
(The request group macro call identifies this user-in file.) 


When the macro call has been executed, $R6 will contain the 
record length of the new user-in file, and S$R7 will contain 
the file status. 


NOTES: 


Example: 


1. 


If argument 1 is a pathname address, SR2 is set 
to zero and the pathname supplied by argument 1 
is placed in $B4. If argument 1 is SCIN, S$R2 is 
set to two. If argument 1 is omitted, $R2 is 
set to one. | 


On return, S$R1l, S$R6, S$R7, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 
0000 -— No error 
All file management get-file and open-file 
error codes may also be returned. See the 
System Messages manual. 


SR6 - Record length of redefined file 


SR7 - File status of redefined file (see 
"Command In") 


SB4 - Address of pathname string of new user-in 
file (if pathname was supplied in argument 
1) 


In this example, the issuing task is to read its input from 
a new user-in file name, “V1124>UDD>TEST>JONES. 


INAA 


SNUIN !'NEWIN 


NEWIN DC '°V1124>UDD>TEST>JONESA' 
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NEW USER OUTPUT 


NEW USER OUTPUT 

Macro Call Name: SNUOUT 

Function Code: 08/05 

Equivalent Command: File Out (FO) 


Redefine or reset the uSer-out file for the task group of 
the issuing task. The user-out file can be redefined by a 
new pathname or reset to the user-out file initially defined 
for the issuing task group. The action taken applies to all 
tasks in the task group from which the command is issued. 


FORMAT: 


[label] SNUOUT [location of pathname address] 
ARGUMENT DESCRIPTION: 


location of pathname address 


Any address form valid for an address register; pro- 
vides the pathname of the file to be used as the new 
user-out file for the issuing task group. If this 
argument is omitted, the file defined by the request 
group macro call (SRQGRP) is used as the user-out file 
for tasks in this task group. 


FUNCTION DESCRIPTION: 


This call allows the issuing task group to use another file 
as the usSer-out file. 


If a pathname is specified in the macro call, the tasks in 
this task group will write their output to the file identi- 
fied by the pathname. 


If the call is written without an argument, the user output 
file identified as the initial output file for this task 


group is used for task output. (The request group macro 
call identifies the initial user-out file.) 
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When the macro call has been executed, SR6 will contain the 
record length of the new user-out file, and $R7 will contain 
its file status. 


NOTES: 1. 


Example: 


The address of the pathname supplied by argument 
1 is placed in $B4, and SR2 is set to zero. If 
this argument is omitted, SR2 is set to one. 


On return, SR1, SR6, SR7, and S$B4 contain the 
following information: 


SR1 - Return status; one of the following: 
0000 — No error 
All file management get-file, create-file, 
and open-file error codes may also be 
returned. See the System Messages manual. 


SR6 - Record length of redefined file 


SR7 - File status of redefined file (see 
"Command In") | 


SB4 - Address of pathname string of new user-out 
file (if a pathname was specified in 
argument 1) 


In this example, the user-out file is reset to its initial 


definition. 


OUTBK SNUOUT 
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OPEN FILE 


OPEN FILE 


Macro Call Name: SOPFIL 
Function Code: 10/50 (preserve), 10/51 (renew) 
Equivalent Command: None 


Initializes and establishes addressability to a file (which 
can be used by any task in the group). You identify the 
File to be opened by supplying its logical file number 
(LFN). 


FORMAT: 


ene | 


[label] SOPFIL [fib address] ie 


ARGUMENT DESCRIPTION: 
fib address 


Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). The FIB must contain a valid LFN and program 
view. 


— 
PRE 


Specifies that this is an existing data file, and that 
labels and data already in the file are to be pre- 
served. Reading starts from the first logical record; 
writing starts at the current logical end-of-file. 
PRESERVE is the default value for this macro call. 


For indexed files only, specifying PRESERVE means that 


a file when opened cannot be opened by anyone else in 
RENEW mode. 
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=a | 
REN 
Specifies that this is a new file, and that no attempt 
should be made to read it (i.e., the file should be 
treated as though it was empty). 


Specifying RENEW means that the file cannot be opened 
by anyone else. 


For disk files, both writing and reading start from 
the first logical record (except for indexed sequen- 
tial files, which cannot be read in this mode). 


For tape files, RENEW is used to rewrite an existing 
file or add a new file to a volume. Write permission 
must be granted in the FIB program view word. 


FUNCTION DESCRIPTION: 


Before this macro call can be issued, the following actions 


must have occurred: 


1. The specified file must physically exist (i.e., it must 
have been created through a create file macro call). 


2. The LFN must have been associated with the external file 
through an associate file, get file, or create file 
macro call (or through an equivalent command). 


If a file is currently opened elsewhere in the system (by 
any LFN in the requesting task group or any other task 
group), the following rules apply: 


1. Opening the file in RENEW mode is not allowed. 


2. Opening an indexed file in PRESERVE mode is not allowed 
if the file is currently open in RENEW mode. 


3. Opening a tape file in any mode is not allowed. 


If an associate file macro call was executed, but a get file 
macro call was not, the open file macro call will attempt to 
reserve the file with exclusive concurrency control. (This 

method of opening a file is not recommended.) | 


A file cannot be opened directly through its pathname. If 
you issue a get file or create file macro call with only a 
pathname (no LFN specified), the system will assign an LEN, 
which you can then use to open the file. 
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If an indexed sequential file is empty (i.e., has been 
created but never opened in RENEW mode), and this file is 
opened in PRESERVE mode, the system converts the open to an 
open in RENEW mode and provides no notification of this 
change. Only write operations will be allowed. A subSse- 
quent read operation will result in a 0203 (illegal func- 
tion) error code. 


The following discussion and rules apply only to magnetic 

tape files. 

1. Certain tape search rules are used when the file is 
opened to locate the required tape file. These rules 
are applied when the tape is opened for data management 
(record-level) access, or when a file name is specified 


and the tape is opened for Storage management (block 
level) access. Table 5-11 defines these rules. 


Table 5-ll. Tape File Search Rules for SOPFIL Macro Call 


File Label Type and FSN. Value in 
Open Mode SGTFIL Call Result 


Labeled tapes opened 
O/FF 
n 


in PRESERVE mode: 
0 
: | 
PF 6 
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Tape positioned to next 
file. 


File name not 
specified 


Tape positioned to nth file. 


Tape poSitioned to next 
file; file name in header 
label is compared against 
specified file name. 


File name is 
specified 


Tape positioned to nth file; 
file name in header label is 
compared against specified 
file name. 


Tape searched in forward 

direction only for a header 
label with a matching file 
name. 


Table 5-11 (cont) Tape File Search Rules for S$OPFIL Macro Call 


File Label Type and FSN° Value in | 
Open Mode a aac ae Call Result 


Tape positioned to next 
file. 


Labeled tape opened 

in RENEW mode (file 

name is always 

required) n 


Tape poSitioned to nth file. 


Tape positioned in forward 
direction only to a file 
with a matching file name. 
If no match is found, the 
new file is appended after 
the end of all existing 
files on the last tape 
volume. 


Tape poSitioned to the next 
file (past the next ware 
mark). 


Unlabeled tapes O/FF 
opened in PRESERVE 


mode (file or volume 


name cannot be 
specified) n 


Tape poSitioned to the nth 
file (past the nth Rape 
mark). 


Unlabeled tapes 0 
opened in RENEW mode 
(file or volume name 
cannot be specified) 


Tape positioned to the next 
file (past the next tape 
mark). 


Tape poSitioned to the nth 
file (past the nth tape 
mark). 


Tape poSitioned forward only 
to the end of existing data; 
the new file is appended 
after the end of all exist- 
ing files on the tape. 


a 
FSN = Tape file sequence number argument in SGTFIL macro call. 


2. For tapes opened in PRESERVE mode, the position of data 
within the file is determined as follows: 


a. If only read permission is granted (FIB program view 
word allows read but not write), the header label 
group is processed and the file positioned directly 
in front of the first data record. 
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b. If only write permission is granted (FIB program 
view word allows write but not read) the header 
label group is processed and the file positioned 
directly after the last data record. This in 
effect, is "append" mode, a way for the user to add 
records to the end of a file without having to read 
past all the existing data records. 


Trailer labels and an end-of-data tape mark are 
written when the file is closed. Files following 
the current file are lost. 


c. If read and write permissions are granted (FIB pro- 
gram view word allows both read and write) the 
header label group is processed and the file posi- 
tioned directly in front of the first data record. 
Any write request issued after the file is opened 
will cause all data records that were read to be 
preserved, and those records that were not read to 
be lost. This procedure can be used to preserve 
part of the file while renewing the rest. 


If no write operations are done and the file is 
closed, no trailer labels are written. Thus files 
located after the current file are preserved. 


If write operations are done, trailer labels and an 
end-of-data tape mark are written when the file is 


closed. Files that follow the current file are 
lost. 


For tapes opened in RENEW mode, the position of data 
within the file is determined as follows. 


a. Creation of the new file is initiated at the current 
tape position. (If the tape is positioned at begin- 
ning of tape (BOT), the volume header label is 
bypassed.) The header label group is written as 
specified in the preceding get file macro call. 
After these actions, the tape is positioned at the 
end of the header label group. 


b. Data and/or files following the current tape posi- 
tion are destroyed when the file is opened. 


As part of the initialization process, this macro call 
verifies that sufficient space is available for buffers and 
control structures. 


This macro call must be issued before any of the data man- 
agement or Storage management macro calls can be executed. 
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The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined through 
the STFIB macro call. 


NOTES: Lie 


Example: 


Tf the first argument is coded, the address of 
the FIB is loaded into S$B4; if the argument is 
omitted, SB4 is assumed to contain the address 
of the FIB. , 


On return, $R1 contains one of the following 
status codes: | 


OO000 - No error 

0205 -—- Illegal argument 

0206 - Unknown or illegal LFN 
0208 - LFN or file already open 
0214 - Bad program view of file 
0217 - Access violation 


0225 - Not enough system memory for buffers or 
structures 


0226 - Not enough user memory for buffers or 
structures | | 


022C - Access control list (ACL) violation 
O22E - Record lock concurrency conflict 
In addition to the above codes, any system 


service codes received by the file manager are 
passed on through SRl. 


This SOPFIL example opens a new file, in which records are 
to be written via the data management macro call(s) that 
follow this macro call. 


Following is a sample sequence of macro calls and FIB used 
to open FILE A for processing. 
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LL $. 


FILE A 


MYFIB 


KEY 


IDXO1 


WRTFIL 


SCRFIL 
SOPFIL 


SWRREC 


Z'O005' 


Z'OOOS5' 
Z'OOOOFFFF' 


““VOL03>SUBINDEX.A>FILE AA' 


! 
IMYFIB, RENEW 


IMYFIB 


FILE A or SGTFIL !WRTFIL 
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(See “Assumptions 
for File System 
Examples" in 
Section 3.) 


(See create file 
macro call) 

(See get file 
macro call) 


(See write record 
macro call) 
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OPERATOR INFORMATION MESSAGE 


OPERATOR INFORMATION MESSAGE 

Macro Call Name: SOPMSG 

Function Code: 09/00 

Equivalent Command: Message (MSG) 


Display an information message on the terminal designated as 
the operator terminal. 


FORMAT : 


[label] SOPMSG [location of IORB address] 
ARGUMENT DESCRIPTION: 


location of IORB address 


Any address form valid for an address register; pro- 
vides the address of the input/output request block 
(IORB) that describes the location and range of the 
output information message. See Appendix A for a 
description of the IORB. 


FUNCTION DESCRIPTION: 


This call enables the issuing task to send a message to the 
system operator. The location of the message and its range 
are specified in the IORB (which is generated by the SIORB 
macro call, or coded by the user). The IORB also specifies 
whether control is to be returned to the issuing task imme- 
diately or the task is to wait until the eReee is 
displayed. 


NOTES: 1. The address of the IORB supplied by argument 1 
is placed in $B4; if this argument is omitted, 
SB4 is assumed to contain the correct address. 


2. On return, S$R1 and S$B4 contain the following 
information: 
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Abbe. 


SR1 - Return status; one of the following: 
OO000 - No error 
0801 - IORB in use (T-bit on) 


0802 - Invalid LRN; or console message 
Suppression in effect 


0803 - Illegal wait or R, S, D, bit in 
TORB is still on 


(The following could occur if the IORB. 


Specified the issuing task was to wait 
the message to be displayed.) 


0104 - Invalid arguments 
0105 - Device not ready 


0106 - Device timeout 


for 


0107 —- Hardware error (check IORB status 


word) 
0108 - Device disabled 
0109 - File mark encountered 
O10A —- Controller unavailable 
0O10B - Device unavailable 
010C - Inconsistent request 
SB4 - Address of IORB 
Example: 


In this example, the SOPMSG macro call is used to write 


the 


message labeled OP MSG on the operator terminal. The wait 


macro call (SWAIT) is later used to block the task until 
message has been received. 
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* 
* 
* 


IORB 


* 
* 
kk. 
OP MSG 
OP MLN 


SOPMSG 


DEFINE THE 
RESV 


TEXT 


TEXT 


DC 
DC 


TEXT 


DC 
DC 


END OF THE 


TEXT 
E QU 


!TORB 


!TORB 


i) 


WoOoWwWWdwwW on 
Ooooordsdo 


— ww.» = «2 w= @ 


OO 


IORB. 


=e 


=e 


THIS CODE EXECUTES WHETHER OR NOT 
OPERATOR'S MESSAGE WAS PHYSICALLY 
WRITTEN TO THE TERMINAL. 


THIS CODE EXECUTES ONLY AFTER THE 
MESSAGE IS PHYSICALLY WRITTEN. 


RSU 


RETURN STATUS. 

T (IN USE) BIT 

W (DON'T WAIT) BIT 
U (USER) BIT 

MBZ 

MBZ 

MBZ 

MUST BE 1 


PCT 


LRN 

MBZ 

B (BYTE INDEX) BIT 
MBZ 

MBZ 

FUNCTION CODE 


I cT2 


BUFFER ADDRESS 
RANGE (IN BYTES) 


(BREAK) BIT 

BIT (MBZ) 

BIT (MBZ) 

(KEYBOARD ECHO) BIT 
(LF) BIT 

(NO CR) BIT 
ODE 


I Dvs 


=QTmROW 


RESIDUAL RANGE 
STATUS WORD 


"A MESSAGE TO THE OPERATOR.' 


2*($-OP_ MSG) 
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OPERATOR RESPONSE MESSAGE 


OPERATOR RESPONSE MESSAGE 
Macro Call Name: SOPRSP 
Function Code: 09/01 
Equivalent Command: None 


Display a message on the operator terminal and place the 
operator's response to that message in a buffer specified by 
the input IORB. 


FORMAT : | 


[label] SOPRSP [location of IORB list address] 


ARGUMENT DESCRIPTION: 


location of IORB list address 


Any address form valid for an address register; pro- 
vides the address of a list specifying the IORBs to be 
used. The format of the IORB list is as follows: 


entry 1 - Address of IORB describing output message 
(to operator terminal) 


entry 2 - Address of IORB describing input message 
(for operator response) 


FUNCTION DESCRIPTION: 


This call enables the issuing task to send a message to the 


system operator and receive the operator's response to that 
message. 


Two IORBs are needed; an IORB describing the output message 
and an IORB describing the input buffer for the response. 


Both IORBs are generated through a SIORB macro call or coded 
by the user. 


The output message IORB describes the location of the output 
message and the size of the output message. 
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The input IORB describes the location:‘of the input buffer 

for the response, the size of the buffer, and whether con- 
trol is to be returned to the issuing task immediately or, 
by setting the W-bit of the input IORB, after the response 
has been received. 


NOTES: 1. The address of the IORB list supplied by argu- 
ment 1 is placed in $B4; if this argument is 
omitted, S$B4 is assumed to contain the correct 
address. 


2. On return, SR1 and $B4 contain the following 
information: | | | 


SR1 - Return status; one of the following: 
O000 - No error 
0801 - IORB in use (T-bit on) 


0802 - Invalid LRN; or console message 
SsuppresSion in effect 


0803 - Illegal wait, or the R, S, D bit in 
the IORB is not zero 


0817 - Memory access violation 

(The following could occur if the IORB 
describing the input buffer specified that 
the issuing task was to wait for the 
response.) 

0104 - Invalid argument 

0105 - Device not ready 


0106 -—- Device timeout 


O107 - Hardware error (check IORB status 
word) 


0108 - Device disabled 
0109 - File mark encountered 


O10A - Controller unavailable 


Q10B - Device unavailable 
010C - Inconsistent request — 
010D - EOT on magnetic tape detected hae? 
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SB4 - Address of input IORB 


Example: 


In this example, the SOPRSP macro call causes the message 


labeled OP ORY to be written on the operator terminal. 


A 


reply from the operator terminal will then be read into the 
= The issuing task will remain blocked 
until the above actions have been completed. 


buffer labeled OP ANS. 


IN RB 


* 
* 
* 
OP ORY 
OP QLN 
OP_ANS 
OP ALN 


SOPRSP 


DC 


!TORB_L 


DEFINE THE IORB LIST. 


<OUT_RB,<IN RB 


DEFINE THE IORBS. 


OUTPUT IORB: 


SAF, 0 

Z'00', B'ooooo0cdo1' 
Z'00', B'o0O00O', Z'1' 
<OP ORY 

OPOLN 
B'0000000000010000' 
0, 0 


INPUT IORB: 


RESV 
TEXT 
TEXT 
DC 
DC 
TEXT 
DC 


END OF 


TEXT 
E QU 
RESV 
EF QU 


IORBS. 


SAF, 0 

Z'00', B'O0000001' 
Z'o00', B'o000', Z'2' 
<OP ANS 

OP ALN 
B'0000000000110000' 
0, 0 

'A QUERY TO THE OPERATOR?! 
2*(S-OP ORY) 

40, 0 

2* (S-OP_ANS) 
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OVERLAY AREA, RELEASE 


OVERLAY AREA, RELEASE 
Macro Call Name: SOVRLS 
Function Code: 07/06 
Equivalent Command: None 


Exit from the calling overlay, decrement the count of users 
maintained for this overlay, and transfer control to the 
Supplied return point. (The overlay must have been 
requested through an overlay area reserve and execute over- 
lay (SOVRSV) macro call.) 


FORMAT: 


[label] SOVRLS [location of return point address] 
ARGUMENT DESCRIPTION: 
location of return point address 


Any address form valid for an address register; pro- 
vides the address of the return point to which control 
is to be transferred. 


FUNCTION DESCRIPTION: 


This call causes an exit from the calling overlay and a 
return to a specified point. The identity of the overlay 
area table (OAT) controlling the overlay iS extracted from 
the task control block of the issuing task. The identity of 
the OAT is cleared from the TCB and the count of the number 
of users of this overlay is decremented in the defining OAT. 
When the count drops to zero (i.e., the task is the last to 
use the reserved area), the overlay area is marked as 
available (i.e., released) and can be reused by a reserve 
area and execute overlay function. Control is transferred 
to the return point supplied by argument 1. 
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NOTES: 1. The return point address supplied by argument 1 
is placed in $B5; if this argument is omitted, 
SB5 is assumed to contain the correct return 
point address. 


2. No return iS made to the caller; control is 
returned to the address supplied in S$B5. All 
registers except SR1l are preserved as they 
existed when the function was executed. 


Example: 


In this example, the calling overlay uses the SOVRLS macro 
call to release its overlay area and return to the caller at 
the return point named OV2 RA. The calling overlay is 
assumed to be the overlay (OVLY2) that was loaded and 
executed as shown in the example for the overlay area 


reserve and execute overlay macro call. 


XLOC OV2_ RA 
SOVRLS 1<OV2_RA 
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OVERLAY AREA RESERVE, 
AND EXECUTE OVERLAY 


OVERLAY AREA RESERVE, AND EXECUTE OVERLAY 
Macro Call Name: SOVRSV 

Function Code: 07/05 

Equivalent Command: None 


Reserve an overlay area defined by the specified overlay 
area table (OAT), increment the user count for that overlay 
area, load the specified floatable overlay, and transfer 
control to the overlay at the specified (or default) entry 
point. (The overlay area must have been defined through a 
create overlay area table macro call.) 


FORMAT: 


[label] SOVRSV [location of overlay idl, 


[location of entry point offset], 
[location of OAT address] 


ARGUMENT DESCRIPTION: 


location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay to be loaded and 


executed. (The overlay id is a binary value generated 
by the Linker.) 


location of entry point offset 


Any address form valid for an address register; pro- 
vides the offset (from the overlay load base) of the 
overlay entry point to which control is to be 
transferred. If this argument is omitted, control is 
transferred to the start address declared to chee 
language processor or the Linker. 
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location of OAT address 


Any address form valid for an address register; pro- 
vides the address of the OAT that defines this overlay 
area. This address was returned by the system when 
the OAT was created through the create overlay area 
table macro call (S$CROAT). 


FUNCTION DESCRIPTION: 


This call causes the system to perform the following: 


thy 


Determine if the issuing task already has an area 
reserved. If so, an illegal overlay nesting (160B) is 
returned. 


If the issuing task has no area reserved, determine 
whether the specified overlay of the bound unit being 
executed by the issuing task is currently resident in 
any of the overlay areas defined by the OAT referred to 
in the call. 


If the overlay is resident, the system increments the 
area's user count and transfers control to the overlay 
at the specified (or default) entry point. 


NOTE: The default OAT is the first OAT in the OAT queue 
of the current bound unit having areas of suf- 
ficient size to contain the requested overlay. 


If the overlay is not resident, the system attempts to 
reserve an overlay area defined by the specified OAT. 

If the overlay area is successfully reserved, the system 
increments the user count for the area, loads the 
specified overlay, and transfers control to the overlay 
at the specified (or default) entry point. 


If no overlay area defined by the specified OAT is 
available, the system suspends the issuing task until an 
area becomes available. When an area becomes available, 
the system reserves it, increments its user count, loads 
the specified overlay, and transfers control to its 
Specified (or default) entry point. 


When control is transferred to the overlay, the system 
records the identity of the defining OAT in the task 


control block of the issuing task. 


The overlay to be loaded must be a uSer Segment with proper 
access rights and the proper size. 
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NOTES: 1. The overlay id supplied by argument 1 is placed 
in SR2; if this argument is omitted, SR2 is 
assumed to contain the overlay id. 


2. The relative displacement of the entry point 
from the overlay base, supplied by argument 2, 
is placed in SR6; if this argument is omitted, a 
value of -1 is placed in S$R6 to designate that 
the default entry point established through the 
language processor or the Linker is to be used. 


3. The address of the overlay area table (OAT), 
Supplied by argument 3, is placed in SB4; if 
this argument is omitted, $B4 is assumed to con- 
tain the address of the OAT to be used. 


4, On normal entry to the overlay, SB4 contains the 
address of the overlay area table (OAT). All 
other registers are preserved as they existed at 
the execution of the call. 


5. On return, $R2 and S$B4 contain the following: 


SR2 - Overlay id (as supplied) 
SB4 - Overlay area table address (as supplied) 


6. If an error occurs, return is made to the 
caller. $R1 contains one of the following 
status codes: 


Olxx - Media error 

0602 - Insufficient system memory 
1602 - Invalid overlay id 

1605 - Illegal start address 

160A - Insufficient memory 

160B - Illegal overlay nesting 
1610 —- Named OAT cannot be found 


Example: 


In this example, the SCROAT macro call is used to create an 
overlay area table of three 512-word entries. (It is 
assumed that no existing OAT controls 512-word entries.) 

The address of the controlling OAT will be stored in the 
field OAT A. Later, the SOVRSV macro call is used to cause 
the overlay named OVLY2 to be loaded into one of the areas 
controlled by the OAT (if it is not already available in one 
of the OAT areas) and then executed at its default entry 
point. | 
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% 


% 


* 


XVAL OVLY2 

CREATE AN OAT IF ONE DOES NOT ALREADY EXIST 
SCROAT !OAT A, =512, =3 

CHECK FOR ERRORS 


BNEZ SR1, ERROR] 


LOAD OVLY2 (IF NECESSARY) AND EXECUTE IT 
SOVRSV =OVLY2,, !OAT A 
CHECK FOR ERRORS 


BNEZ SR1, ERROR2 


DEFINE NORMAL RETURN ADDRESS FOR OVERLAY 


XDEF (OV2 RA, $) 
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OVERLAY, EXECUTE 


OVERLAY, EXECUTE 

Macro Call Name: SOVEXC 
Function Code: 07/00 
Equivalent Command: None 


Load the specified overlay of the bound unit being executed 
by the issuing task. Transfer control to the overlay at the 
Specified entry point or at the start address declared to 
the language processor or to the Linker. 


FORMAT : 


[label] SOVEXC [location of overlay id], 
[location of entry point offset], 
[location of overlay base address] 


ARGUMENT DESCRIPTION: 
location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay to be executed. 


(The overlay id is a binary value generated by the 
Linker.) 


location of entry point offset 


Any address form valid for an address register; pro- 
vides the offset (from the overlay load base) of the 
overlay entry point to which control is to be trans- 
ferred. If this argument is omitted, control is 
transferred to the start address declared to the 
language processor or the Linker. 


FUNCTION DESCRIPTION: © 


This call causes the named overlay to be loaded at the fixed 
(virtual) address established at link time. 
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If argument 2 is specified, the value it provides is the 
offset from the overlay load base. Control is transferred 
to that location. (Note that the offset must be less than 
the overlay size.) If argument 2 is not specified, control 
is transferred to the start address declared to the language 
processor or the Linker (default start address). If argu- 
ment 3 is specified, it provides the location of the overlay 
load base. 


The overlay to be loaded and executed must have the proper 
access rights and must not be of zero length. 


NOTES: 1. The overlay id supplied by argument 1 is placed 
in S$R2; if this argument is omitted, SR2 is 
assumed to contain the overlay id. 


2. The relative displacement of the entry point 
from the overlay load base, supplied by argument 
2, is placed in SR6; if this argument is omit- 
ted, a value of -1 is placed in $R6 to designate 
that the default entry point is to be used. 


3. The overlay base address supplied by argument 3 
is placed in $B4; if this argument is omitted, 
the system assumes a null address. 


4. The address where the overlay is actually loaded 
is ascertained as follows: 


a. If the overlay is nonfloatable, it is loaded 
at the fixed address established at link 
time. 


b. If the referenced overlay is floatable and 
null pointer value is specified as the base 
address, the overlay is loaded into memory 
obtained by the loader from the memory pool 
of the issuing task's task group. 


c. If the overlay is floatable, and a nonnull 
pointer value is specified as the base 
address, the overlay is loaded at the 
Specified base address. 


5. On overlay entry, SR1, SR2, SR6, and SB4 contain 
the following information: 


SR1 -— 0000 


SR2 - Overlay id 
SR6 - Entry point offset 
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Example: 


If an error is made in the calling Sequence, 
return is to the caller. S$R1 contains, one of 
the following status codes: 


Olxx 
0602 
0817 
0829 
1602 
1604 


160A 


Media error 

Insufficient system memroy 
Memory access violation 

Group available memory exceeded 
Invalid overlay id 


Illegal start address (offset greater 
than or equal to overlay size) 


Insufficient memory 


In this example, the SOVEXC macro call causes the overlay 
named DPOSIT (of the bound unit being executed) to be loaded 
and started at the entry point whose offset is named ENTRY2. 
The example assumes that ENTRY2 has been defined as an 
external value when the bound unit was linked (or possibly 
when its source unit was assembled or compiled). 


XVAL DPOSIT, ENTRY2 
SOVE XC =DPOSIT, =ENTRY2 
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OVERLAY, LOAD 


OVERLAY, LOAD 


Macro Call Name: SOVLD 
Function Code: 07/01 
Equivalent Command: None 


Load the specified overlay of the bound unit being executed 
by the issuing task. Return control to the isSuaing task. 


FORMAT : 


[label] SOVLD [location of overlay id], 
[location of overlay base address] 


ARGUMENT DESCRIPTION: 
location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay to be loaded. 
(The overlay id is a binary value generated by the 
Linker.) 


FUNCTION DESCRIPTION: 


This macro call causes the loading of the named overlay at 
the fixed (virtual) address established at Link time. When 
the overlay is successfully loaded, control is returned to 
the issuing task with the overlay base address in $B4 and 
the overlay default start address offset in SR64. (The over- 
lay default start address is that address specified to the 
language processor or the Linker.) 


NOTES: 1. The location of the overlay id, supplied by 
argument 1, is placed in SR2. If argument 1 is 
omitted, SR2 is assumed to contain the location 
of the overlay id. 


2. The location of the overlay base address, sup- 


plied by argument 2, is placed in S$B4; if this 
argument is omitted, a null address is assumed. 
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The address where the overlay is actually loaded 
is ascertained as follows: 


a. 


If the overlay is nonfloatable, it is loaded 
at the fixed address established at link 
time. 


If the referenced overlay is floatable and 

null pointer value is specified as the base 
address, the overlay is loaded into memory 

obtained by the loader from the memory pool 
of the issuing task's task group. 


If the overlay is floatable, and a nonnull 
pointer value is specified as the base 
address, the overlay is loaded at the 
specified base address. 


On return, SR1l, S$R2, SR6, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 


00CcCO0 - No error 
OQlxx -—- Media error 


0601 - Requested contiguous memory exceeds 
defined pool size 


Q602 - Insufficient system memory 

0817 - Memory access violation 

0829 - Group available memory exceeded 
1602 - Invalid overlay id 


160A - Insufficient memory 


SR2 - Overlay id (on a successful return) 


SR6 - Overlay default start address offset (on a 


successful return) 


SB4 -— Overlay base address 
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Example: 


In this example, the SOVLD macro call causes the overlay 
named DPOSIT (of the bound unit being executed) to be loaded 
but not executed. Upon return from the system, SB4 will 
contain the overlay base address or a null pointer value for 
Floatable overlays. For nonfloatable overlays, SB4 is not 
applicable, and $R6 will contain the offset from its base 
address to its default start address. The overlay base 
address and the offset to the default start address will be 
saved in OVLY A and OVLY E, respectively. Thus, the overlay 
can be entered later at its default start address by an 
instruction sequence such as that shown in the middle of the 
example. When the overlay is no longer needed, it is 
unloaded by the SOVUN (overlay unload) macro call. 


* 
- LOAD THE DPOSIT OVERLAY 
* 
XVAL DPOSIT 
SOVLD =DPOSIT 
* 
BNEZ SR1, BAD LD CHECK FOR LOAD ERRORS 
‘: e 
* SAVE THE BASE ADDRESS AND ENTRY POINT OFFSET 
* 
STB SB4, OVLY A. 
STR SR6, OVLY_E 
n e 
* JUMP TO DPOSIT'S DEFAULT ENTRY POINT 
* 
LDB SB4, OVLY A 
LDR SR1, OVLY_E 
JMP SB4.SR1 
¥ e 
* UNLOAD THE OVERLAY 
* 
SOVUN =DPOSIT, !OVLY A 
OVLY A DC <S 
OVLY E DC 00 
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OVERLAY RELEASE, WAIT, 
AND RECALL 


OVERLAY RELEASE, WAIT, AND RECALL 
Macro Call Name: SOVRCL 

Function Code: 07/07 

Equivalent Command: None 


Exit from the calling overlay. When completion status has 
been posted to the specified request block, perform an over- 
lay area reserve and execute overlay function for the 
specified overlay. Use the current definition of the over- 
lay control table (OCT) and overlay area table (OAT). The 
calling overlay must have been loaded through the overlay 
area reserve and execute overlay macro call (SOVRSV). 


FORMAT: 


[label] SOVRCL [location of overlay idl, 
[location of entry point offset], 
[location of request block address] 


ARGUMENT DESCRIPTION: 
location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay to be called when 
the specified request block has been posted as com- 
plete. (The overlay id is a binary value generated by 
the Linker.) If this argument is omitted, the overlay 
that issued this macro call is recalled. 


location of entry point offset 


Any address form valid for an address register; pro- 
vides the offset (from the overlay load base) of the 
overlay entry point to which control is to be trans- 
ferred. If this argument is omitted, control is 
transferred to the start address declared to the 
language processor or the Linker. 
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location of request block address 


Any address form valid for an address register; pro- 
vides the address of the request block whose comple- 
tion status is to be awaited. 


FUNCTION DESCRIPTION: 


This call enables the task to exit from the calling overlay 
and then to load the same or another overlay when the 
specified request block is posted as complete. fThe call 
releases the overlay previously reserved by the overlay area 
reserve and execute overlay (SOVRSV) macro call. This over- 
lay is identified by the currently reserved overlay area 
field in the task control block of the issuing task. After 
the identity of the currently reserved area is retrieved, 
the field in the task control block is cleared and the usage 
count of the area is decremented. If this task is the last 
task uSing the area, the area is released aS a resource of 
the associated overlay area table (OAT), and tasks waiting 
for an area are posted where applicable. 


The identity of the associated OAT is saved. The issuing 
task is then forced to wait on the specified request block 
(RB). When the requested block is posted as completed, the 
overlay area table is restored and the overlay area reserve 
and execute overlay (SOVRSV) function is performed to recall 
the specified overlay. The address and completion status of 
the request block are returned to the called overlay. 


If argument 1 specifies an overlay that is resident in the 
area defined by this OAT, the area's user count is incre- 
mented and control is transferred to the overlay at the 
specified (or default) entry point (argument 2). If the 
overlay is not resident, an attempt is made to reserve an 
overlay area controlled by the OAT. If the area is success- 
fully reserved, the user count is incremented and the over- 
lay is loaded and executed. If no overlay area defined by 
the OAT is available, the issuing task is suspended until an 
area becomes available. When the area is available, the 
count is incremented and the overlay is loaded and executed. 


NOTES: 1. The overlay id supplied by argument 1 is placed 
in SR2; if this argument is omitted, a value of 
-~1 is placed in SR2 to designate that the issu- 
ing overlay is to be recalled. 


2. The relative displacement of the entry point 
from the overlay base, supplied by argument 2, 
is placed in SR6; if this argument is omitted, a 
value of -1 is placed in S$R6 to designate that 
the default entry point established through the 
language processor or the Linker is to be uSed. 
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3. The address of the request block to be waited 
on, supplied by argument 3, is placed in $B4; if 
this argument is omitted, $B4 is assumed to con- 
tain the address of the request block. 3 


4, On entry to the called overlay (no error in 
calling sequence), SR1 and S$B4 contain the fol- 
lowing information: 


SR1 - Posted completion status of specified 
request block, as follows: 


0000 -— No error 


OOOO-FFFF - Request-Specific posted com- 
pletion status 


SB4 - Start address of called overlay (used by 
debugger) or address of OAT (if no debug- 
ging in effect) 


5. If the calling sequence is in error, return is 
made to the calling overlay. S$R1, $R2, and $B4 
contain the following information: 


SR1 -— Return Status; one of the following: 


0802 - Invalid LRN 

0803 - Illegal wait 

1602 - Invalid overlay id 

1605 - Illegal start address 

1617 - OAT has no overlay to release 


SR2 - Overlay id value (as supplied) 
SR6 - Overlay entry point offset (as supplied) 


SB4 - Request block address (as supplied) 


Example: 


In the following example, the task is to exit from the cur- 
rent overlay and wait for the task request block named TRB1 
to be marked as complete before loading overlay OVLY2 and 
executing it at its default entry point. Note that the 
overlay to be exited from and the overlay to be loaded and 
executed are controlled by the OAT whose identity was 
Stored in the task control block of the issuing task by a 
previously issued overlay area reserve and execute overlay 
macro call. | | 
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TRB1 


XVAL OVLY2 

STRB 7 

SOVRCL =OVLY2,, !TRB1 
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OVERLAY STATUS 

Macro Call Name: $OVST 
Function Code: 07/03 
Equivalent Command: None 


Return the current status of the Specified overlay. Among 
the items of status information returned are: 


Oo Sharable or nonsSharable bound unit 
o Patched or nonpatched overlay 


FORMAT: 

[label] SOVST [location of overlay id] 
ARGUMENT DESCRIPTION: 
location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay whose status is 
desired. (The overlay id is a binary value generated 
by the Linker.) 


FUNCTION DESCRIPTION: 


This call causes the system to return an overlay Status word 
in SR2. The description of SR2, below, contains the detail 
of the overlay status word. Bits 5 and 6 are meaningful 
only to the call/cancel/exit controller. 


When this call is executed, the overlay entry point is 
returned in SR6, the overlay size in SR7, and the overlay 
base address in $B4, | 


NOTES: 1. The overlay id supplied by argument 1 is placed 


in SR2; if this argument is omitted, SR2 is 
assumed to contain the required overlay id. 
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On return, SR1l, S$R2, SR6, SR7, and SB4 contain 


the following 


information: 


SR1 - Return status; one of the following: 


0000 —- No error 
1601 - Invalid overlay id 


SR2 - Overlay 


Bit 0 - 


Bit 1 - 


Bit 11 


Bit 12 


Bit 13 


status indicator word: 


Set to 1 if bound unit Sharable; 
otherwise 0. 


Set to 1 if overlay permanently 
loaded; otherwise 0. 


Set to 1 if slow load section 
present; otherwise 0. 


Set to 1 if overlay floatable; 
otherwise 0. 


Set to 1 if bound unit can be 
executed in system task group; 
otherwise 0. 


Set to 1 if overlay resident in 
memory; otherwise 0; meaningful 
only to call/cancel/exit 
controller. 


Set to 1 if overlay has been 
called but has not exited; other- 
wise 0; meaningful only to call/ 
cancel/exit controller. 


through 9 —- Reserved for system 


use. 


Set to l if overlay contains 
initialized relocatable pointers; 
otherwise O. 


Set to 1 if overlay contains 
symbolic references; otherwise 0. 


Set to 1 if overlay defines 
symbolic names; otherwise 0. 


Set to 1 if overlay is patched; 
otherwise 0. 
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Bit 14 - Set to 1 if overlay must be 
executed in SAF mode; otherwise 
on 


Bit 15 - Set to 1 if overlay must be 
executed in LAF mode; otherwise 
GO 


SR6 - Overlay default entry point (as specified 
by the language processor or Linker); 
given as a word offset from the overlay 
base address. 


SR7 - Overlay size in words (0000 is returned if 
the size is 64K words). 


SB4 - Base address of overlay if permanently 
| loaded or nonfloatable. 


Example: 


In this example, the SOVST macro call is used to determine 
the status of the overlay named DPOSIT, which is an overlay 
of the bound unit being executed. If the overlay is float- 
able, the get memory macro call (SGMEM) obtains memory for 
the overlay. The overlay execute macro call (SOVEXC) then 
loads the overlay and starts it at its default entry point. 
To simplify the example, the return status will not be 
checked for possible errors. 


* 


i‘ NAME THE STATUS INDICATORS TO BE USED. 
Cas EQU B'O0001000000000000! 
7 DECLARE THE OVERLAY'S NAME. 

. AVAL DPOS IT 

. GET THE OVERLAY'S STATUS. 


SOVST DPOSIT 


* GET MEMORY FOR IT IF IT IS FLOATABLE. 
* 
LB =S$R2, FLOAT 
BBF >LOAD 
LDV SR6,0 
SGMEM =S$R7,WAIT 
* 
* LOAD AND EXECUTE THE OVERLAY. 
‘ , 
LOAD SOVEXC DPOSIT 
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OVERLAY, UNLOAD 


OVERLAY, UNLOAD 

Macro Call Name: SQOVUN 
Function Code: 07/0C 
Equivalent Command: None 


Unload the specified overlay of the bound unit that contains 
the procedure being executed by the issuing task. 


FORMAT: 


[label] SOVUN [location of overlay id], 
[location of overlay base address], 
[location of return point address] 


ARGUMENT DESCRIPTION: 
location of overlay id 


Any address form valid for an address register; pro- 
vides the overlay id of the overlay to be unloaded. 
(The overlay id is a binary value generated by the 
Linker.) 


location of overlay base address 


Any address form valid for an address register; pro- 
vides the base address of the overlay to be unloaded. 
The load overlay and execute overlay macro calls cause 
the overlay to be loaded at the fixed (virtual) 
address established at Link time. 


location of return point address 


Any address form valid for an address register; pro- 
vides the address of the return point to which control 
will be returned after the macro call is executed. If 
this argument is omitted, the address of the first 
word following the generated monitor call sequence is 
assumed to be the return point address. 
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FUNCTION DESCRIPTION: 


This call causes the named overlay to be unloaded. The 
overlay must not share a segment with any other overlay of 
the bound unit. You must have the proper access rights to 
the overlay. 


NOTES: 1. The overlay id supplied by argument 1 is placed 
in S$R2; if this argument is omitted, $R2 is 
assumed to contain the overlay id. 


2. The overlay base address supplied by argument 2 
18S placed in S$B4; if this argument is omitted, 
SB4 is assumed to contain the base address. 


3. The return point address supplied by argument 3 
is placed in $B5; if this argument is omitted, 
the return point address is assumed to be the 
address of the first word following the 
generated monitor call sequence. 


4. The overlay being unloaded must be floatable, 
and the memory it occupies must have been 
obtained by a get memory macro call, either 
directly by the user or indirectly by either the 
overlay load or overlay execute macro call. If 
that memory was obtained directly by the user, 
then the address of the first word of the memory 
block must have been specified as the base 
address of the overlay when it was loaded. 


9. On return, SR1 contains one of the following 
Status codes: 


0000 -— No error 
0817 - Memory access violation 


0818 —- No task group with specified id exists 
(system software error) 


081B - Roll-in of online task group attempted 
(system software error) 


081C - Roll-in attempted when the batch group 
was not rolled out (system software 
error) 

O81E - Unrecoverable media error during roll-in 

081F - Group not suspended when roll-in 


attempted (system software error) 
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Example: 


see the example given for the overlay load (SOVLD) macro 
call. 
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PARAMETER BLOCK 


PARAMETER BLOCK 

Macro Call Name: SPRBLK 
Function Code: None 
Equivalent Command: None 


Generate a parameter block that is equivalent to the argu- 
ment list portion of the task request block. 


FORMAT : 


[label] SPRBLK [user argument l], 
[fuser argument 2], 


[user argument n] 
ARGUMENT DESCRIPTION: 
user argument 1 ... user argument n 


User argument values; a parameter block is generated 
containing the specified user argument values in the 
parameter poSitions that correspond to the argument 
positions in the S$PRBLK macro call. Pathname argu- 
ments that include a trailing blank should be 

enclosed in single or double (' or ") quotation marks. 


If an argument value of zero is specified before the 
last argument, an argument pointer of Zeros is 
generated in the corresponding position in the argu- 
ment list. 


FUNCTION DESCRIPTION: 
A parameter block is equivalent to the argument list portion 


of the task request block (see the task request block macro 
call). 
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ie 


A parameter block is the standard means of providing addi- 
tional arguments to the request group, spawn group, and 
request batch macro calls. 


NOTE: This macro call cannot be used in programs 
written in SAF/LAF independent code (SLIC). 
See the Program Preparation manual for more 
information about SAF/LAF independent code. 


Example: 

In this example, the $PRBLK macro call is used to specialize 
a control file for the command processor by replacing &1 and 
&2 by -XREF and -—PRINT. (The parameter block format is 
given in Appendix A.) 


ARGS 1 SPRBLK -XREF, -PRINT 
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PERSON IDENTIFICATION - 


PERSON IDENTIFICATION 
Macro Call Name: S$PERID 
Function Code: 14/01 
Equivalent Command: None 


Returns the person component of the calling task group's 
user identification to a 12-character receiving field. 


FORMAT : 


[label] SPERID [location of person id field address] 


ARGUMENT DESCRIPTION: 
location of person id field address 


Any address form valid for an address register; pro- 
vides the address of a 12-character, aligned, nonvary- 
ing field into which the system will place the person 
component of the user identification associated with 
the isSuing task group. 


FUNCTION DESCRIPTION: 


This call returns the person component (i.e., the user's 
personal identification) of the task group's user identifi- 
cation to a field in the issuing task. The person identi-_ 
fication returned is that entered as part of the LOGIN com- 
mand that established. the user as a primary or secondary 
user of this task group See the Commands manual for 
details. : 


The entire user id is returned by the user identification 
(SUSRID) macro call. 


NOTES: 1. The address of the receiving person id field, 
supplied by argument 1, is placed in SB4; if 
this argument is omitted, $B4 is assumed to con- 
tain the address of the field. 
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Ate, 


2. On return, $R1 contains one of the following 
status codes: 


0000 - No error 
0817 —- Memory access violation 


3. On return, $B4 contains the address of the 
receiving field. 


Example: 


In the following example, a 12-character field is set up in 
the issuing task and the S$PERID macro call is issued to 


place the person identification of the task group in that 
field. 


IDO2 SPERID I!PRIDFL 


PRIDFL RESV 6,0 
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READ BLOCK 


READ BLOCK 
Macro Call Name: SRDBLK 
Function Codes: 12/00 (normal), 12/01 (tape mark), 12/02 
| (beginning of tape), 12/03 (space), 12/04 (end 
of tape) | | 


Equivalent Command: None 


Read (i.e., transfer) a block from a file to a buffer in 
main memory; you must supply a buffer and specify both the 
size of the block and its relative location in the file. 


FORMAT: 
, NORMAL 


[label] SRDBLK [fib address]]j<,BOT 


ARGUMENT DESCRIPTION: 
fib address 


Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). The following FIB entries are required. 
logical file number 
program view 
Should include buffer alignment and whether the 
next read operation is synchronous or 
asynchronous. 


user buffer pointer 


transfer size 
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Aide. 


eas 


NOR 


TM 


SPACE 


(spa 


EOT 


block size 


Must be a multiple of the physical sector size. 


block number 


For disk resident files this mode argument indicates 
that the block identified in the block number entry in 
the FIB is transferred from the file to the buffer 
area. 


For nondisk files this mode argument indicates that 
the next block is to be transferred from the file to 
the buffer. 


NORMAL is the default value for this macro call. 


(For tape-resident files only.) This mode argument 
indicates that the tape is to be moved forward or 
backward the number of tape marks specified in the 
block number entry in the FIB. Positioning is to a 
point immediately following the nth tape mark. A 
positive value indicates forward movement; a negative 
value indicates backward movement. 


(For tape-resident files only.) This mode argument 
indicates that the tape is to be moved forward or 
backward the number of blocks specified in the FIB 
block number entry. Positioning is to a point imme- 
diately following the nth block. A positive value in 
the block number entry indicates forward movement; a 
negative value indicates backward movement. 


(For tape-resident files only.) This mode argument 
causes the tape to be positioned to its logical end, 
Which is defined as the occurrence of two tape marks 
in succession. Positioning is to a point immediately 
following the second tape mark. 
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FUNCTION DESCRIPTION: 


Before this macro call is executed, the LFN must have been 
opened (see open file macro call) with a FIB program view 
word that allows access via storage management (bit 0 is 1) 
and allows read operations (bit 1 is 1). In order to read 
the file sequentially, it is necessary only to issue suc- 
cessive read block macro calls in NORMAL mode, which causes 
the block-number entry to be incremented by 1 after each 
transfer. If there is not sufficient data in the block 
being transferred to fill the buffer, the transfer size 
entry in the FIB is set by the system to the number of bytes 
read and a return code of 0000 is delivered. 


After completion of a TM, BOT, or EOT operation, the block- 
number entry in the FIB is automatically reset to 0; how- 
ever, a SPACE operation causes the system to specify the 
actual relative number of the next block that would be read 
by a read block macro call. If a tape mark is encountered 
during a SPACE operation, the operation is terminated and a 
return-Status code of 0O21F is delivered. In addition, if 
the end-of-reel is reached, a 0105 error code (device not 
ready) is delivered; however, if the end-of-tape is reached, 
it is treated like a normal operation and a return code of 
0000 is delivered on successful completion. 


Only one asynchronous I/O operation per file can be out- 
Standing at any given time. 


The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined by the 
STFIB macro call. 


NOTES: 1. If the first argument is coded, the address of 
the FIB is loaded into $B4; if the argument is 
omitted, $B4 is assumed to contain the address 
of the FIB. 


2. Upon return, S$R1 contains one of the following 
return codes: 


0000 - No error 

0203 - Illegal function 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 
0207 - LFN not open 

O20A - Address out of file 
0217 - Access violation 

O21F - End of file 


In addition to the above codes, any system 
service codes received by the storage manager 
are passed on through SRl. 
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Example: 


In this example the FIB is defined as follows: 


BLKFIB DC ZYO0Cs" LFN=5 
DC Z*EOOO' PROGRAM VIEW = ALLOW READ/WRITE 
SYNCHRONOUS PROCESSING | 
DC <BLKBUF BUFFER POINTER 
RESV 2- SAF 
DC 256 TRANSFER SIZE = 256 
DC 256 BLOCK SIZE = 256 
DC Z‘'oooo0000n0' 


Based on the above FIB, block 0, which is 256 bytes long, is 
transferred to a buffer, labeled BLKBUF, in main memory. 


SRDBLK !'BLKFIB, NORMAL 
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READ EXTERNAL SWITCHES 


READ EXTERNAL SWITCHES 
Macro Call Name: S$RDSW 
Function Code: 0B/00 
Equivalent Command: None 


Return the current value of the specified switches in the 
task group's external switch word; return the inclusive 
logical OR of the current settings. 


FORMAT : 


[label] SRDSW external switch name, 
fexternal switch name], 


[external switch name] 


ARGUMENT DESCRIPTION: 
external switch name ... external switch name 


A single hexadecimal digit specifying the external 
Switch in the task group's external switch word to be 
read. A maximum of 16 external switch names (0 
through F) can be specified. If no arguments are Sup- 
plied, S$R2 is assumed to contain the switches to be 
read. If ALL is specified, all switches are read. 


FUNCTION DESCRIPTION: 


This call provides a mask by which the current setting of 
selected switches in the task group's external switch word 
can be read. 


SR2 is the mask word. Each bit that is 1 in $R2 causes the 
corresponding bit in the external switch word to be read. 
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BE 


When the SRDSW macro call is executed, $R2 contains the cur- 
rent value of the external switch word. Bit 11 (bit-test 
indicator) of the I-register provides an indication of the 
setting of the switches, as follows: 


o If bit 11 is 0, none of the switches read was on. 
o If bit 11 is 1, at least one of the switches read was on. 


NOTES: 1. The bits corresponding to the external switches 
in the arguments are set on in S$R2; if no argu- 
ments are supplied, $R2 is assumed to contain 
the mask to be used. If ALL is specified for 
any argument, all bits are set on in SR2. 


2. On return, S$R2 and the I-register contain the 
Following information: 


SR2 - Current value of external switch word 
I-register (Bit 11) - Inclusive OR of switches 
read: 
Q -—- No switch read was on 


l1 - At least one switch read was on 


Example: 


In this example, the SRDSW macro call is used to read the 
specified switches in the external switch word of the task 
group in which the issuing task is executing. The contents 
of SR2 (the mask word) are to be 2F4A so that switches 2, 4, 
5, 6, 7, 9, C, and E will be read, inclusive ORed, and 
Stored in the central processor's bit indicator. To 
illustrate: . 


Word: 2 F 4 A 


Bits: 0123 4567 89AB CDEF 
0010 1111 ©0100 1010 


Switches: 2 4567 9 CE 


The BBT instruction is used to transfer control to the rou- 
tine DO IT if one or more of the switches is turned on. 


RDSWA SRDSW- 2,4,5,6,7,9,C,E 
BBT DO_IT 
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READ RECORD 


READ RECORD 
Macro Call Name: SRDREC 


Function Code: 11/10 (next), 11/11 (key), 11/12 (position 
equal), 11/13 (position greater than), 11/14 
(position greater than or equal), 11/15 (position 
forward), 11/16 (position backward) 


Equivalent Command: None 


Retrieves one logical record from a file to your record area 
or merely positions the read pointer to a desired record. 
Whether to retrieve or position is specified by the second 
(i1.@€., mode) argument. | 


FORMAT: 


, NEXT 

,KEY 

, POSEQ 
[label] SRDREC [fib address]|< ,POSGR 

, POSGREO 

, POSFWD 

, POSBWD 


ARGUMENT DESCRIPTION: 
fib address 
Any address form valid for an address register; pro- 


vides the location of the file information block 
(FIB). 
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bees, 


KEY 


(For all files.) This mode argument indicates that 
the record pointed to by the read pointer is to be 
read next. The read pointer is set to the next 
logical record in the file after the read is complete. 
Only active records are read (i.e., deleted records 
are skipped unless bit 11 in the program view FIB 
entry is set to 1). This is the default for this 
macro call. You must code the following FIB entries: 


logical file number 

program view (record area alignment) 
user record pointer | 
input record length 


After the record is transferred to main memory, the 
system updates the following FIB entries: 


output record length 

output record address 
(Serial sequence number if device file; BSN if 
tape file; simple key unless relative access 


specified at open time). 


This mode is referred to as read next. 


(For disk files accessed by key, only.) This mode 
argument indicates that the record identified by the 
key value pointed to by the FIB is to be read. The 
read pointer is set to the next logical record in the 
File after the read is complete. Only active records 
are read unless bit 11 in the program view FIB entry 
is set to 1. You must code the following FIB entries: 


logical file number 
program view (record and key area alignment) 
user-record pointer 


input record length 
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input key pointer 
input key format 
input key length 


After the record is transferred to main memory, the 
system updates the following FIB entries: | 


output record length 
output record address 
(Simple or relative key.) 
This mode is referred to as read with key. 


sPOSEQ\ 
(PEQ 


(For disk files accessed by key, only.) This mode 
argument positions the read pointer to the first logi- 
cal record in the file whose key is equal to the one 
specified in the FIB. It is not necessary for the 
record pointed to to be active. The record can be 
read via a read next macro call (See above). You must 
code the following FIB entries: 

logical file number 

program view 

input key pointer 

input key format 

input key length 


This mode is referred to as read position equal. 


gas 
PGR 


(For disk files accessed by key, only.) This mode 
argument positions the read and pointer to the first 
logical record in the file whose key is greater than 
the one specified in the FIB. It is not necessary for 
the record pointed to to be active. The record can be 
read via a read next macro call (see above). The same 
FIB entries as for POSEQ, above, must be coded. This 
mode is referred to as read position greater than. 
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{(POSGREOQ\ 
(PGE ) 


(For disk files accessed by key, only.) This mode 
argument positions the read pointer to the first logi- 
cal record in the file whose key is greater than or 
equal to the one specified in the FIB. It is not nec- 
essary for the record pointed to to be active. The 
record can be read via a read next macro call (see 
above). The same FIB entries as for POSEQ, above, 
must be coded. This mode is referred to as read posi- 
tion greater than or equal. 


—"s 
PFD 


(For tape-resident and relative files only.) This 
mode argument moves the read pointer forward the 
number of record positions specified by the key value 
identified in the FIB (but not beyond the end-of- 
file). It is not necessary for the record pointed to 
to be active. The record can be read via a read next 
macro call (See above). The same FIB entries as for 
POSEQ, above, musSt be coded. This mode is referred to 
as read poSition forward. 


ela | 

PBD 
(For tape-resident and relative files only). This 
mode argument is the same as for POSFWD (above) except 
that the pointer is moved backwards the number of 
record positions specified by the key value in the FIB 
(but not before the first record). This mode is 
referred to as read poSition backward. 


FUNCTION DESCRIPTION: 


Before this macro call can be executed, the LFN must have 
been opened (see the open file macro call) with a program 
view word that allows access via data management (bit 0 is 
0) and allows read operations (bit 1 is 1). The read 
pointer is a logical pointer to the next record to be read; 
it 1S maintained separately from the write pointer. There 
is one read pointer per file per user. At open-file time 
the pointer is set to the first record in the file, and is 
modified by each read record operation. 


The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined by the 
STFIB macro call. 
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The following illustrate the effects of read actions accord- 
ing to file organizations. 


File Organizations | Effects of Read Actions 
Sequential Read next causes sequential read. Read 
with key causes direct read.' A simple 


key is used. 


Relative Read next causes a Sequential read. Read 
with key causes a direct read.' A 
relative or simple key can be used. 


Indexed Read next causes a sequential read. The 
records returned are in logical sequence 
according to primary key value. (This is 
not necessarily in the same time-dependent 
or physical sequence that the records were 
loaded into the file.) Read with key 
causes a direct read.! A primary key or 
Simple key can be used. ; 


Fixed Relative Read next causes a Sequential read. Read 
with key causes a direct read. A relative 
key is used. 


oK 


Device Files Read next causes a sequential read, pro- 
vided the device can be read and was 
defined as a readable device. 


NOTES: 1. If the first argument is coded, the address of 
the FIB is loaded into $B4; if the argument is 
omitted, $B4 is assumed to contain the address 
of the FIB. 


2. On return, $R1 contains one of the following 
status codes: 


OO0O0 - No error | 

0203 - Illegal function 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 
0207 - LFN not open 

O20A - Address out of file 

O20E - Record not found 

0217 - Access violation 

0219 - No current record pointer 


1A read, with any position mode, positions the read pointer to 
the desired record, so that a subsequent READ-NEXT will retrieve 
that record. | 
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O21A 
O21E 
O21F 
022A 
022B 


Record length error 

Key length or location error 

End of file 

Record lock overflow or not defined 
Requested record is locked 


In addition to the above codes, any system 
service codes received by the data manager are 
passed on through SRl. 


Example: 


This example assumes that the address of the FIB (i.e., 
MYFIB) was loaded in SB4. In addition, the required entries 
in the FIB are those defined in "Assumptions for File System 
Examples" in Section 3. Also, it is assumed that the file 
was reserved (see "Get File"), and that the open file macro 
call was coded with the LFN and program-view entries as 
defined in the example for the open file macro call. 


The macro call is then specified as follows: 


SRDREC ,NEXT 


After the record is read, the system updates the following 
entries, which you can interrogate using the FIB offset 


tags: 


F_ ORL 
FORA 


(Output record length) 
(Output record address) 
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RELEASE DIRECTORY rs 


7 / 
Nu 


RELEASE DIRECTORY 

Macro Call: S$RLDIR 

Function Code: 10/A5 

Equivalent Command: Release (RL) 


Deletes a previously created directory from the system; all 
of the directory's attributes, including its name, are 
removed from the immediately superior directory that 
describes it, and all space allocated to the directory is 


released. This function is usually done outside program 
execution. 


FORMAT: 


[label] SRLDIR [argument structure address] 
ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register; pro- 
vides the location of the parameter structure defined 


below. The parameter structure must contain the 
following entry. 


pathname pointer 


A 4-byte address, which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII space char- 


acter) that identifies the directory to be 
released. 
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FUNCTION DESCRIPTION: 

This macro call, in effect, reverses the create directory 
action, provided it has no subordinate directories or files 
(i.e., if the directory to be released contains a suborordi- 
nate directory or file it is not released and an error code 
is returned). In addition, if it is currently the working 


directory in any task group, the directory cannot be 
released. 


NOTES: 1. If the argument is coded, the address of the 
parameter structure is loaded into S$B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the parameter structure. 


2. On return, S$R1 contains one of the following 
status codes: 


0000 - Successful completion 

0201 - Illegal pathname 

0205 - Illegal argument 

0209 - Named dieseeary not found 

020C - Volume not found 

0213 - Cannot provide requested concurrency 
0220 - Attempted deletion of nonempty directory 


0222 - Pathname cannot be expanded, no working 
directory 


0225 —- Not enough system memory for buffers or 
structures 


0226 —- Not enough user memory for buffers or 
structures | 


022C - Access control list (ACL) violation 
In addition to the above codes, any system 


service codes received by the file manager are 
passed on through SR1l. 


5-267 CBO08 


Examples: 


In this example, the S$RLDIR macro call releases the direc- 
tory created in the create directory example (i.e., 
SUBINDEX.A). The system uses the first entry to identify 


the directory to be released. The release directory macro 
call is coded as: 


SUBDIR DC <DIR PTH 


DIRPTH DC '“VOL03>SUBINDEX. AA! 
SRLDIR ! SUBDIR 
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RELEASE FILE 


RELEASE FILE 

Macro Call Name: SRLFIL 
Function Code: 10/35 

Equivalent Command: Release (RL) 


Delete a previously created file from the system. All the 

file's attributes, including its name, are removed from the 
directory that describes it, and all space allocated to the 
file is released. You identify the file to be released by 

Supplying either a logical file number (LFN) or a pathname. 
This function is usually done outside program execution. 


FORMAT: 


[label] SRLFIL f[argument structure address] 
ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


logical file number 


A 2-byte logical file number (LFN) uSed to refer 
to the file; must be a binary number in the 
range 0 through 255; or blank (which indicates 
that an LFN is not specified). 


pathname pointer 


A 4-byte address, which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII space char- 
acter) that identifies the directory in the file 
hierarchy in which the file to be released is 
found (as well as the name of the file itself). 
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Zeros in this entry indicate that a pathname is 
not specified. 


FUNCTION DESCRIPTION: 


This macro call, in effect, reverses the create file action, 
provided the file is neither open in this task group, nor 
reserved by another task group. In the case of the former, 
a return status code of 0208 is loaded in S$Rl; in the latter 
case, the file is released after the other task group is 
finished using it. 


The file to be deleted can be specified by (1) an LFN only, 
or (2) a pathname only. If only an LFN is specified, the 
file must have been created or reserved (through a create 


file or get file macro call, or equivalent command) with 
that LFN. 


For files other than disk files, the release file function 
is equivalent to the remove file function. 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into S$B4; if the 
argument is omitted, $B4 is assumed to contain 
the address of the parameter structure. 


2. On return, $R1 contains one of the following 
status codes: | 


0000 —- No error 

0201 - Illegal pathname 

0205 - Illegal argument 

0206 -— Unknown or illegal LFN 


0208 -— LFN or file currently open in same task 
group 


0209 - Named file or directory not found 
O20C - Volume not found 


0222 —- Pathname cannot be expanded, no working 
directory 


0225 —- Not enough system memory for buffers or 
structures 


0226 - Not enough user memory for buffers or 
structures 
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O22C - Access control list (ACL) violation 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In this example, the macro call releases the file created in 
the create file macro call example. To do this, it refer- 
ences the same argument structure as the S$CRFIL macro call; 
the system, in turn, uses the first two entries to identify 
the file to be released. The release file macro call is 
coded as: 


SRLFIL !FILE A 
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RELEASE SEMAPHORE ~ 


RELEASE SEMAPHORE 

Macro Call Name: SRLSM 
Function Code: 06/03 
Equivalent Command: None 


Release a resource controlled by the specified semaphore and 
activate the first waiting task enqueued on that semaphore 


if the value of the semaphore is negative (both actions are 
known collectively as a V-op). 


FORMAT : 


[label] SRLSM _ [location of semaphore identifier] 


ARGUMENT DESCRIPTION: 
location of semaphore identifier 


Any address form valid for a data register; provides 
the two ASCII characters that identify the semaphore 
controlling the reSource to be released. 


FUNCTION DESCRIPTION: 


A task issues a release semaphore macro call when it has 
Finished using the resource controlled by the semaphore 
indicated in the call. The semaphore must have been pre- 
viously defined by a define semaphore macro call. | 


When the release function is executed, the counter whose 


initial value was set in the define semaphore macro call is 
incremented. 


If tasks are waiting for the resource to become available, 
the first task queued on this semaphore is awakened. 


NOTES: 1. The semaphore identifier supplied by argument 1 

| is placed in SR6; if this argument is omitted, 
SR1 is assumed to contain the correct 
identifier. 
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2. On return, SR1 and SR6 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 — No error 
0502 -— Semaphore not defined 


SR6 - Semaphore identifier (as supplied) 


Example: 


see the example given for the define Semaphore macro call. 
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RELEASE TERMINAL Ss 


RELEASE TERMINAL 
Macro Call Name: SRLTML 
Function Code: 17/04 


Equivalent Command: None 


Issued by a task group to release a Secondary user terminal 
back to the listener component after the terminal file has 
been closed and removed. 


FORMAT: 


[label] SRLTML [location of terminal LRN], 
[location of status code] 


ARGUMENT DESCRIPTION: 


location of terminal LRN 


Any address form valid for a data register; provides 


the logical resource number (LRN) of the terminal to 
be released. 


location of status code 


Any address form valid for a data register; provides a 
completion status code that will be posted when the 
request is marked as terminated. Acceptable status 
codes are: 


0000 - Normal release 
3920 - Secondary login rejected 


FUNCTION DESCRIPTION: 


This call is used to return a secondary user terminal that 
was previously obtained by the calling task group through a 
request terminal (SRQOTML) macro call. Until this call is 


issued, the terminal is reserved for the task group that 
issued the SROTML call. | 
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NOTES: 1. The LRN of the addressed terminal, supplied by 
argument 1, is placed in SR6; if this argument 
is omitted, S$R6 is assumed to contain the 
terminal's LRN. 


2. The status code supplied by argument 2 is placed 
in S$R7; if this argument is omitted, S$R7 is 
assumed to contain the status code. 


3. On return, SRl1 contains one of the following 
status codes: 


Q0000 - Terminal successfully released 

3902 - Invalid LRN 

3921 - Terminal not assigned to task group 
3928 - Unable to release terminal; file not 


removed 
Example: 


In this example, the SRLTML macro call is used to release a 
terminal previously reserved through a request terminal 
call. Note that the terminal LRN is stored in word 0 of the 
area that received the login parameters (See the request 
terminal macro call). In this example, the LRN was later 
aie in the field LRN STR. A status code of 0000 is to be 
used. 


REL_TA SRLTML =LRN STR, =0 
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REMOVE FILE 


REMOVE FILE 

Macrs Call Name: S$RMFIL 

Function Code: 10/25 

Equivalent Command: Remove (REMOVE) 


Cancels the file reservation previously established by a get 
file macro call. You identify the file to be removed by 
supplying either a logical file number (LFN) or a pathname. 
This function is usually done outside program execution. 


FORMAT: 


[label] SRMFIL [argument structure address] 
ARGUMENT DESCRIPTION: 


argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


logical file number 


A 2-byte logical file number (LFN) used to refer 
to the file; must be a binary number from 0 
through 255, or ASCII blanks (2020), which indi- 
cate that an LFN is not specified. 


pathname pointer 


A 4-byte address, which may be any address form 
valid for an address register; it points to a 
pathname (which must end with an ASCII space 
character) that identifies the directory in the 
file hierarchy in which the file to be removed 
is found (as well as the name of the file. 
itself). Binary zeros in this entry indicate 
that a pathname is not specified. 
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FUNCTION DESCRIPTION: 


This macro call removes the file reservation established for 
the specified file, provided it is not currently open (see 
"Open File") in the task group in which you are executing. 
It does not dissociate the LFN from a pathname (see 
"Dissociate File"). 


Also, if the file is a temporary file (see "Create File"), 
this macro call has the same effect as the release file 
macro call previously described. 


The file to be removed can be specified only by either an 
LFN or a pathname. When only an LFN is specified, the file 
must have been reserved previously with a get file or create 
file macro call or with an equivalent command. 


A remove file macro call does not remove a file that was 
reserved through the command GET; the command REMOVE must be 
used. 


Since the remove file macro call removes all information 
about the file from the system, Subsequent get file macro 
calls may require that multiple directory levels be searched 
to again locate the file. Thus, the remove file macro call 
Should be used carefully and only after all references to 
the file are complete. 


NOTES: 1. If the argument is coded, the address of the 
parameter structure is loaded into $B4; if the 
argument is omitted, SB4 is assumed to contain 
the address of the parameter structure. 


2. On return, SR1 contains one of the following 
Status codes: 


0000 No error 

0201 - Illegal pathname 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 


0208 - LFN or file currently open in same task 
group 


0209 - Named file or directory not found 


020C - Volume not found 
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0222 - 
U225°°= 
0226 - 


O2Z29° = 


Pathname cannot be expanded, no working 


directory 


Not enough system memory for buffers or 


structures 


Not enough user memory for buffers or 


structures 


File not known to task group 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In the following example, the macro call specifies an argu- 
ment structure built by a previous get file macro call; this 
technique, as opposed to building a Separate argument struc- 
ture, results in using fewer bytes of memory while achieving 
The macro call is coded as shown in two 


the cancellation. 
examples: 


Example 1: WRTFIL 


Example 2: WRTFIL 


FILE A 


DC 
DC 
SRMFIL 


DC 

DC 
RESV 
DC 
SRMFIL 
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5 LNF = 5 

2.0 

IWRTFIL 

Z'2020' NO LFN 

<FILE A PATHNAME POINTER 
2-SAF 

'“VOLO3>SUB>FILE AA! 
IWRTFIL - 
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RENAME FILE/RENAME DIRECTORY 


RENAME FILE/RENAME DIRECTORY 


Macro Call Name: SRNFIL 
Function Code: 10/40 
Equivalent Command: Rename (RENAME) 


Change the name of a disk file or directory to the name 
specified by the macro call. You identify the disk file or 
directory to be renamed by supplying either a logical file 
number (LFN) or a pathname. This function is usually done 
outside program execution. 


FORMAT : 


[label] SRNFIL [argument structure address] 


ARGUMENT DESCRIPTION: 
argument structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


logical file number 


A 2-byte logical file number (LFN) used to refer 
to the file; must be a binary number in the 
range 0 through 255, or ASCII blanks (2020), 
which indicate that an LFN is not specified. 


pathname pointer 


A 4-byte address, which may be any address form 
valid for an address register; points to a path- 
name (which must end with an ASCII space char- 
acter) that identifies the file or directory 
whose name is to be changed. Binary zeros in 
this entry indicate that a pathname is not 
specified. | 
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new name 
A l- to 12-byte name, specifying the new name of 
the file or directory; must be a simple name 
(i.e., must not contain " ", "", " ", etc.). 


FUNCTION DESCRIPTION: 


This call changes the name of the specified file or direc- 
tory. However, the volume major directory cannot be renamed 
(any attempt to do so will cause a status code of 0228 to be 
returned in SR1). To rename the volume major directory, use 
the Create Volume command (see the Commands manual). 


The file can be renamed by specifying (1) an LFN only or (2) 
a pathname only. If only an LFN is specified, the file must 
have been reserved (through a create file or get file macro 

call, or equivalent command) with that LFN. 


NOTES: 1. If the argument is coded, the address of the 
parameter structure is loaded into SB4; if the 
argument is omitted, SB4 is assumed to contain 
the address of the parameter structure. 


2. On return, S$R1 contains one of the following 
status codes: 


0000 - No error 

0201 - Illegal pathname 

0205 - Illegal argument 

0206 -—- Unknown or illegal LFN 

0209 - Named file or directory not found 
O020C - Volume not found 


0212 - Attempted creation of existing file or 
directory 


0213 - Cannot provide requested file concurrency 


0222 - Pathname cannot be expanded, no working 
directory. 


0225 - Not enough system memory for buffers or 
structures 


0226 - Not enough user memory for buffers or 
structures > 


5-2 80 CBO08 


0228 - Illegal file type 
Q022C - Access control list (ACL) violation 


In addition to the above codes, any system 


service codes received by the file manager are 


passed on through SR1. 


Example: 


In this example, assume a file has been created in the 


directory SUB. INDEX.A by the name of FILEA. Its full path- 
name is VOL03>SUB.INDEX.A>FILEA. In addition this file is 


reserved with LFN=2. User executes this code: 


ANEWAA SRNFIL ~~ !NEWNM1 

NEWNM1 DC 2 LFN = 2 
RESV 2,0 NO PATHNAME POINTER 
DC 'OLDF_1A' 


The result is that FILEA in the directory SUB.INDEX.A is 


renamed to OLDF 1. 
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REPORT ERROR CONDITION 


REPORT ERROR CONDITION 


Macro Call Name: SRPTER 


Function Code: 0OF/00 


Equivalent Command: None 


Report error conditions that follow the standard error code 
format and provide optional error message expansion text. 


FORMAT : 


[label] 


SRPTER [location of component error code], 
[location of category/specific error codes], 
[location of meSsage expansion text size], 
[location of message expansion text] 


ARGUMENT DESCRIPTION: 


location of component error code 


Any address form valid for a data register; provides 
the 2-byte hexadecimal error code of the software 
component that reports the error. The first byte must 
be zero; the second byte is the component error code 
(reporting component). The symbolic name, if any, 
Specified in a Linker EDEF directive for the task 
Start address is included with the message. 


location of category/specific error codes 


Any address form valid for a data register; provides 
the 2-byte hexadecimal error category code and spe- 

cific error condition. Byte 0 is the error code of 
the component that detects the error; byte 1 is the 

specific error condition within that component. 
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location of message expansion text size 


Any address form valid for a data register; provides 
the size of the message expansion text that further 
explains the error. The text size must include the 
Slew byte (format control byte), which is the first 
byte in the message expansion text (the actual text 
begins with the second byte); see "Printer Driver" in 
Section 6. If this argument is omitted, no expansion 
message text has been provided. 


location of message expansion text 


Any address form valid for an address register; pro- 
vides the address of the message expansion that fur- 
ther defines the error. The message expansion text 
must include the slew byte as the first byte. If 
argument 3 is omitted, and this argument is omitted, 
there is no expansion text. 


FUNCTION DESCRIPTION: 


This macro call enables the task to report error conditions 
that follow the standard system error code format (see the 
System Messages manual). Error conditions are recorded on 
the error-out file unless the category/specific error code 
(argument 2) is 01, in which caSe they are recorded on the 
operator terminal. The component, category, and specific 
error codes must be provided; message text is optional. 


NOTES: 1. The component error code supplied by argument l 
1s placed in $R3; if this argument is omitted, 
SR3 is assumed to contain the component error 
code. 


2. The category and specific error codes supplied 
by argument 2 are placed in $R7; if this argu- 
ment is omitted, SR1l is assumed to contain the 
category and specific error codes and SR7 is set 
to the value contained in SRl. 


3. The expansion text size supplied by argument 3 
is placed in SR6; if this argument is omitted, 
SR6 is set to zero to indicate that no expansion 
text is provided. 


4. The address of the expansion text supplied by 
argument 4 is placed in $B3; if this argument is 
omitted, $B3 is assumed to contain the address 
of the expansion text (if argument 3 was 
specified). 
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5. On return, SR7 contains the following: 


SR7 - Codes: byte 0 is error category code; 
byte 1 is specific error code. 


Example: 


In this example, the user in macro call (SUSIN) is used to 
attempt to read a line from the user input file. If the 
attempt is unsuccessful, the SRPTER macro call is used to 
report this fact. The error message produced will include 
the expansion text PROCESS ABORTED. The abort group request 
macro call (SABGRQ) is then used to abort processing of the 
current task group request with a completion Status of one. 
Processing will begin with the next group request, if any. 


* NAME MY OWN COMPONENT CODE. 

*& 

MY CC EQU X'g5! 

* 

* READ THE USER INPUT FILE. 

* 
SUSIN !1IN BUF,=IN BLN 

: x 

IF UNSUCCESSFUL GO TO BAD RD. 

: i? 
BNEZ $R1,BAD RD 

* ° | | 

* REPORT AN UNSUCCESSFUL USER INPUT READ 

x AND ABORT THE CURRENT GROUP REQUEST. 

* 

BAD RD $RPTER  =MY CC; MY COMPONENT CODE 

| | ERROR CODE IS IN S$R1 

=X TLNG; EXPANSION TEXT LENGTH 
1XTTEXT LOCATION OF EXPANSION TEXT 

SABGRO =1 TERMINATION STATUS 

X TEXT TEXT 'APROCESS ABORTED! | 

X TLNG EQU 2* ($-X_ TEXT) 
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REQUEST BATCH 


REQUEST BATCH 


Macro Call Name: SROBAT 


Function Code: 0OQE/00 
Equivalent Command: Enter Batch Request (EBR) 


Add a request to the queue of command processor files to be 


processed by the command processor executing in the batch 
task group. 


FORMAT : 


[label] SRQBAT [location of address of argument list], 
[location of address of fixed parameter block] 


ARGUMENT DESCRIPTION: 
location of address of argument list 


Any address form valid for an address register; pro- 
vides the address of the argument list, which can be 
generated by the parameter block macro call (SPRBLK), 
to be used to build the batch request block. The 
batch request block is built in the system area of 
memory, and is used by the command processor to 
specialize commands read from the command-in file. 


location of address of fixed parameter block 


Any address form valid for an address register; pro- 
vides the address of a fixed parameter block, which 
can be generated by the parameter block macro call. 
This parameter block has the following arguments: 


Argument 1 


A string specifying the user id to be asSociated 
with this batch request (for system use). The 
user id currently associated with the issuing 
task group will be used when the call is exe- 
cuted from a user task group. 
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Argument 2 


A pathname string specifying the command-in and 
the initial user-in files for the batch request. 
A nonzero value is required. 


Argument 3 


A pathname string specifying the error-out and 
initial user-out files for this batch request. 
If this entry is zero, one of the following 
assumptions is made: 


o If the pathname string specifying the 
command-in and initial user-in files (in- 
path) specifies a disk device, the pathname 
for the output files is in-path.AO. 


o If in-path specifies an interactive terminal, 
the pathname for the output files is the same 
as in-path. 


o If in-path specifies an input-only device, 
the pathname for the output files is null. 


Argument 4 


A pathname string specifying the initial value 
of the working directory for this batch request. 


FUNCTION DESCRIPTION: 


This call causes a request to execute the commands contained 
in the file identified by the second byte in the fixed 
parameter block (argument 2) to be queued against the batch 
task group. The batch task group has a first-in/first-—out 
queue of command processor files. 


If the batch task group is dormant when the SRQBAT macro 
call is issued, execution begins immediately; otherwise, the 
request is queued. 


The command processor is executed as the lead task of the 
batch task group. Since the command processor obtains its 
commands from the file named in the Second entry of the 
fixed parameter block, the file must begin with a command. 


Batch requests cannot be waited upon. 
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NOTES: 1. The address of the argument list to be used to 
build the request block, supplied by argument l, 
is placed in $B4; if this argument is omitted, 
SB4 is assumed to contain the correct address. 


2. The address of the fixed parameter block, sup- 
plied by argument 2, is placed in $B5; if this 
argument is omitted, $B5 is assumed to contain 
the correct address. 


3. On return, S$R1 contains one of the following 
Status codes: 


0000 - No error 
0209 - Invalid pathname 


Example: 


In this example, the S$ROBAT macro call causes a request to 
execute the command contained in the file 
“V1124>UDD>TEST>JONES>ASM TST to be queued against the 
batch task group. This file will also be used as the user- 
in file. Since argument 23 is null, the user-out and error- 
out files will default to “V1124>UDD>TEST>JONES ASM TST.AO. 
The user id and the initial working directory will be 
JONES.TEST.B and “V1124>UDD>TEST>JONES, respectively. The 
arguments -XREF and -PRINT will be passed to the command 
processor to specialize the control file ASM TST (&1 and &2 
in the control file will be replaced by -XREF and -PRINT, 
respectively). The SPRBLK macro call used in this example 
is described earlier in this section. 


SRQOBAT !ARGS, !INFO 


INFO SPRBLK “V1124>UDD>TEST>JONES>ASM TST,; NULL USER-OUT 
“V1124>UDD>TEST>JONES 
ARGS SPRBLK -XREF, -PRINT 
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REQUEST CLOCK 


REQUEST CLOCK 

Macro Call Name: SRQCL 
Function Code: 05/00 
Equivalent Command: None 


Request the clock manager to mark the specified clock 


request block (CRB) as complete when the interval specified 
in that CRB has elapsed. 


FORMAT : 


[label] SROCL [location of CRB address] 
ARGUMENT DESCRIPTION: 


location of CRB address 


Any address form valid for an address register; pro- 
vides the address of the clock request block to be 
posted when its specified time interval has elapsed. 


FUNCTION DESCTRIPTION: 
This call connects the specified CRB to the timer queue. 


If the clock request block is not cyclic (see "Clock Request 
Block" earlier in this section), when the specified interval 
elapses, the CRB is dequeued from the timer queue. Another 
SROCL macro call must be issued to requeue the CRB. Note 
that a noncyclic CRB can specify an absolute time value 
rather than an interval. 


If the CRB is cyclic, when the specified interval elapses, 
the CRB is posted and a new request for the originally 
specified interval is automatically initiated. The auto- 
matic resetting continues until a cancel clock request 
(SCNCRQ) macro call is issued. A cyclic CRB cannot have a 


time interval of zero, and cannot specify an absolute time 
value. | 
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( NOTES: 1. The address of the CRB to be connected, supplied 
- by argument 1, is placed in $B4; if this argu- 
ment is omitted, S$B4 is assumed to contain the 
correct address. 


2. On return, SR1 and S$B4 contain the following 
information: 


SR1 - Return status; one of the following: 
O000 - No error 


0401 - Illegal time value (zero value for 
cyclic CRB) 


0402 - Invalid LRN 
0403 - Invalid basic timer specified 
SB4 - Address of CRB 
Example: 


See the example given for the wait on request list macro 
call later in this section. 


a Pas 
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REQUEST GROUP 


REQUEST GROUP 

Macro Call Name: SRQGRP 

Function Code: 0OD/00 

Equivalent Command: Enter Group Request (EGR) - 


Request the execution of the lead task of a specified task 
group. The request is placed in the first-in/first- ~out 
request queue maintained for that task. 


FORMAT: 


[label] SRQGRP [location of group identifier], 
[location of address of argument list], 
[location of address of fixed parameter block] 


ARGUMENT DESCRIPTION: 
location of group identifier 


Any address form valid for a data register; provides 
the group identification of the task group to be 
requested. This task group must have been previously 
defined by a create group macro call. 


location of address of argument list 


Any address form valid for an address register; pro- 
vides the address of the argument list, which can be 
generated by the parameter block macro call to be used 
to specialize a request block that will be used to 
request the lead task. 


location of address of fixed parameter block 
Any address form valid for an address register; pro- 
vides the address of a fixed parameter block (which 


can be generated by the parameter block macro call). 
This parameter block has the following arguments: 
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Argument 1] 


A string specifying the user id to be associated 
with this request (for system use). If this 
entry is zero, the user id currently associated 
with the issuing task group will be used at the 
time the call is executed from a user task 
group. 


Argument 2 


A pathname string specifying the command-in and 
initial user-in files for this request for the 
lead task of the referenced task group. If this 
entry is zero, no command-in and initial user-in 
Files will be available to the group. However, 
the group can later obtain a user-in file by 
means of the new uSer input macro call. A non- 
zero entry iS required if the command processor 
is the lead task. | 


Argument 3 


A pathname string specifying the error-out and 
initial user-out files for this request of the 
task group. If this entry is zero, one of the 
following assumptions is made when the call is 
executed: 


o If the pathname string specifying the 
command-in and initial user-in files (in- 
path) specifies a disk device, the pathname 
for the output files is in-path.AO. 


o If in-path specifies an interactive terminal, 
the pathname for the output files is the same 
as in-path. 


o If in-path specifies an input-only device, 
the pathname for the output files is null. 


Argument 4 
A pathname string specifying the initial value 


of the working directory for this request of the 
referenced task group. 
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FUNCTION DESCRIPTION: 


This call initiates the execution of the lead task of a task 
group previously created by a create group macro call. If 
the task group is dormant at the time the request group 
macro call is issued, execution begins immediately. If the 
task group has been activated by a previous request group 
function and has not yet terminated, execution of this 
request group macro call begins when the group becomes 
dormant. 


Execution begins with the lead task specified in the create 
group macro call. The second argument of the request group 
macro call provides an argument list to be used to special- 
ize a request block that is, in turn, used to request the 
lead task. (This request block is built in space taken from 
the memory pool of the requested group.) 


It iS not possible to wait on the execution of a request 
group macro call. 


NOTES: 1. The group id supplied by argument 1 is placed in 
SR2; if argument 2 is omitted, $R2 is assumed to 
contain the group id to be used. 


2. The address of the argument list supplied by 
argument 2 is placed in $B4; if this argument is 
omitted, SB4 is assumed to contain the address 
of the list. 


3. The address of the fixed parameter block sup- 
plied by argument 3 is placed in $B5; if this 
argument is omitted, $B5 is assumed to contain 
the address of the fixed parameter block to be 
used. 


4. On return, S$R1 contains one of the following 
Status codes: 


OO00 -—- No error 


0601 - Insufficient memory 
0602 - Insufficient memory 
O806 -—- Group id not currently defined 
160B - Insufficient memory 
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Example: 


In this example, the SROGRP macro call causes a request to 
execute the commands contained in the file 
“V1124>UDD>TEST>JONES>ASM TST to be queued against the Q2 
task group. (It is assumed that task group Q2 has already 
been created with the command processor as its lead task. 
See the create group macro call for information on creating 
task groups.) The ASM TST file will also be used as the 
user-in file. The file *V1124>UDD>TEST>JONES>L>ASM_TST.AO 
will be used as both the user-out file and the error-out 
file. The user id and the initial working directory will be 
JONES. TEST.M and “V1124>UDD>TEST>JONES, respectively. The 
arguments -XREF and -PRINT will be passed to the command 
processor (group 02's lead task) to Specialize the control 
file ASM TST (&1 and &2, in the control file, will be 
replaced by -XREF and -PRINT, respectively). (See this sec- 
tion for a description of the SPRBLK macro used in this 
example.) 


SROGRP ='92',!ARGS,!INFO 


INFO SPRBLK , 1124>UDD>TEST>JONES>ASM TST; 
“V1124>UDD>TEST>JONES>L>ASM TST AO; 
*“V1124>UDD>TEST>JONES ~ a 

ARGS SPRBLK -XREF,-PRINT 
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REQUEST 1/O -_ 


REQUEST I/O 

Macro Call Name: SRQIO 
Function Code: 02/00 
Poni ent Command: None 


Request an I/O transfer in which the device involved in the 
transfer and the parameters defining the transfer are 


identified in the I/O request block (IORB) referred to in 
the call. , 


FORMAT : 


[label] S$RQIO [location of IORB address] 


ARGUMENT DESCRIPTION: 
location of IORB address 


Any address form valid for an address register; pro- 
vides the address of the IORB containing the device 
designation and all information about the nature of 
the I/O transfer. The IORB can be hand-coded or 
constructed through the SIORBD or SIORB macro calls. 


FUNCTION DESCRIPTION: 
This call requests an I/O transfer using a defining IORB. 


You should initially reserve the device named in the IORB. 
Device reservation can be accomplished by the get file 
(SGTFIL) macro call using device-level access (i.e., the 
pathname is in the form SPD dev_name [volid]). 


The IORB requires a logical resource number (LRN) to refer 
to the device. The LRN can be obtained by issuing a get 
file information (SGIFIL) macro call. The LRN returned by 
the SGIFIL call will be the LRN assigned to the device at 
system building time. 
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The address of the IORB supplied by argument 1] 
is placed in $B4; if this argument is omitted, 
SB4 is assumed to contain the address of the 
IORB to be used. 


On return, SR] and SB4 contain the following 
information: 


SR1 - Return 


0000 


0801 


0802 


0803 


If the 
task is to wait for the completion of the 
request, one of the following codes could 
be returned: 


0104 


0105 


0106 


0107 


0108 


0109 


O10A 


O10B 


O10C 


O10OD 


0817 


Status; one of the following: 
No error 

IORB in use (t~-bit on) 
Invalid LRN 


Illegal wait or the R/S/D bit in 
the IORB is nonzero 


IORB specifies that the issuing 


Invalid arguments 
Device not ready 
Device timeout 


Hardware error (check IORB status 
word) 


Device disabled 

File mark encountered 
Controller unavailable 
Device unavailable 
Inconsistent request 


Magnetic tape EOT marker (reflec- 
tive strip) detected 


Memory access violation 


SB4 - Address of IORB 
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Examples: 


In this example, the SRQIO macro call is used to request an 
I/O transfer involving a device whose logical resource 
number is 143. The device has been reserved by a get file 
macro call; its LRN has been obtained by a get file informa- 
tion macro call. In addition to the LRN, the IORB provides 
the following information about the I/O transfer: 


o The issuing task is to be suspended until the request is 
complete. 


o The address of the buffer to be used in the I/O transfer 
is BUFAD. 7 


o The buffer begins in the left byte of BUFAD. 
o The buffer is 326 bytes long. 


AFOO] SROIO !'TORB21 


IORB21  SIORB 143,WAIT,,BUFAD,L, 326 
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REQUEST SEMAPHORE 


REQUEST SEMAPHORE 

Macro Call Name: SROSM 
Function Code: 06/00 
Equivalent Command: None 


Request the reservation of a resource controlled by the 
semaphore specified in the indicated semaphore request block 
(SRB). If it is available, reserve the resource. If the 
resource is not available, queue the SRB until the resource 
becomes available. 


FORMAT: 


[label] SRQOSM [location of SRB address] 
ARGUMENT DESCRIPTION: 


location of SRB address 


Any address form valid for an address register; pro- 
vides the address of the semaphore request block to be 
queued if the resource is not available. See the 
Semaphore request block (SSRB) macro call later in 
this section. 


FUNCTION DESCRIPTION: 


This call is an asynchronous request for a reSource control- 
led by the semaphore identified in the semaphore request 
block (SRB). The semaphore itself must have been defined by 
a define semaphore macro call. The semaphore request block 
can be generated by a SSRB macro call. 


When the request semaphore macro call is executed, the 
counter whoSe initial value was established by the define 
semaphore macro call is decremented by l. 


If the resource is available, it is reserved. If the 


resource is not available, the SRB is queued until the 
resource becomes available. 


5-297 CBO8 


If WAIT was specified in argument 2 of the $SRB macro call, 
the issuing task is suspended until the resource becomes 
available. The resource is then reserved, the SRB is marked 
as terminated, and control is returned to the isSuing task. 


If argument 2 of the $SRB macro call is not WAIT, control is 
immediately returned to the issuing task, which can then 
perform other processing. When the resource becomes avail- 
able, it is reserved and the SRB is marked as terminated. 
The issuing task can then use the test, wait, or wait on 
request list macro calls to check the completion status of 
the SRB. (Alternatively, the task can use the request-task 
or post-Semaphore termination options.) 


NOTES: 1. The address of the SRB supplied in argument 1 is 
placed in $B4; if this argument is omitted, $B4 
1s assumed to contain the SRB address. 


2. On return, $R1 and $B4 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 — No error 
0502 - Illegal SRB 


SB4 - Address of SRB 
Example: 


In this example the SRQSM and SWAIT macro calls are used to 
replace the P-op on semaphore TH used in the example given 
for the define semaphore macro call. This technique allows 
the requesting task to start the process of reserving a 
resource before it is actually needed and continuing concur- 
rent processing until the resource is required (at which 
time the requesting task will wait for the semaphore request 
block). Processing then continues as in the define sema- 
phore example. 
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Bin, 


+ * 


+ + 


SRB 


OTART THE PROCESS OF CAPTURING A RESOURCE BY ISSUING 
A REQUEST SEMAPHORE CALL TO RESERVE A RESOURCE 


SROSM !SRB 


NOW CONTINUE NORMAL PROCESSING 


ROUTINE TO FINISH GETTING A RESOURCE 

WAIT FOR THE REQUEST SEMAPHORE CALL TO FINISH 
SWAIT ! SRB 

NOW LOCK THE FREE RESOURCE LIST 
SRSVSM ="EK 

NOW TAKE A RESOURCE FROM THE FREE RESOURCE LIST 


THEN UNLOCK THE FREE RESOURCE LIST 
SRLSM ="'LK' 


NOW THE RESOURCE IS RESERVED 


SSRB TH, WAIT 
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REQUEST TASK 


REQUEST TASK 

Macro Call Name: SRQTSK 

Function Code: 0C/00 

Equivalent Command: Enter Task Request (ETR) 


Request the execution of a previously created task within 
the same task group from which this request is issued. 


FORMAT : 


[label] SROTSK [location of request block address] 
ARGUMENT DESCRIPTION: 


location of reguest block address 


Any address form valid for an address register; pro- 
vides the address of the task request block that iden- 
tifies the requested task and specifies whether the 
issuing task is to wait for the completion of the 
request. 


FUNCTION DESCRIPTION: 


This call activates a task that was previously defined by a 

create task macro call. The request task macro call allows 
a running task to request the execution of another task. 

The issuing task must supply a task request block that iden- 

tifies the requested task and the characteristics of the 

request. 


A task request block is constructed through the STRB macro 
call. The first argument of the STRB macro call specifies 
the logical resource number (LRN) of the requested task. 
The second and third arguments specify whether or not the 
issuing task is to be suspended until the request is com- 
plete. The fourth argument specifies the start address of 
the task. 
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Using the LRN supplied in the request block, the task man- 
ager ascertains the task control block of the requested | 
task. The task manager then places the request block in the 
request queue of the requested task. If the request queue 
waS previously empty, the task is queued to its priority 
level. If the priority level was empty, it is activated. 

In addition, if the newly activated priority level is higher 
than that of the calling task, the task manager (operating 

at the priority level of the calling task) is interrupted 

and the requested task begins execution. | 


When the priority level of the calling task again becomes 

the highest active priority level, the task manager checks 

the task request block to ascertain if the calling task is 

to wait for the completion of this request (for the 

requested task) before continuing. If the calling task is ste 
to wait (and the requested task has not already signaled its 
completion relative to the request), the task manager asso- 
ciates the identity of the calling (and now waiting) task 

with the request block for the requested task. The task 
manager then removes the calling task from its priority 

level and activates the next task in the queue. If the 

calling task is not to wait for completion of this request f 
for the requested task, the task manager returns control to 

the calling task. 


The calling task can explicitly supply the address of the 
requested task's entry point in the request block it uses. 
If it does not, the requested task's entry point, derived 
when the task was created or last terminated, is used. 


When a requested task is entered, the task manager provides 
the address of the request block that is being honored. 
This address is that of the first request block in the 
request queue for the priority level of the requested task. 


If a calling task waits for the completion of its request 
for a requested task, the task manager returns the comple- 
tion status of the request to the calling task when the 
latter regains control. (See also the wait and wait on 
request list macro calls.) 


NOTES: 1. The address supplied by argument 1 is placed in 
SB4; if this argument is omitted, $B4 is assumed 
to contain the address of the task request block 
for the task. 


2. On return, SR1 and $B4 contain the following 
information: 
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SR1 - Return status; one of the following: 
0000 - No error 
0801 - Request block in use 
0802 -—- Invalid LRN used in request block 


0803 - Illegal wait (a task cannot wait on 
a request for itself) 


If wait specified: 
OOOO0-FFFF - Completion status 
SB4 - Address of task request block 


Example: 


In this example, the SRQTSK macro call is used to request 
the execution of the task created in the first example for 
the create task macro call (assuming that both macro calls 
are executed in the same task group). The task request 
block used is generated so that the issuing task will not be 
suspended awaiting completion of the requested task, the 
semaphore named TD will be V-oped at completion of the 
requested task, and the requested task will be started at 
entry point ENTRY3 instead of the address specified when the 
task was created. The task request block is also to contain 
the argument -PRINT, and by default will contain no addi- 
tional space for use by the requested task. 


SRQOTSK 'TRB 


TRB STRB 10,NWAIT,SM=TD; 
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REQUEST TERMINAL 


REQUEST TERMINAL 

Macro Call Name: SROQTML 
Function Code: 17/03 
Equivalent Command: None 


Permit the issuing task group to accept a user who is log- 
ging into that task group through the listener component. 


FORMAT: 


[label] SROTML [location of terminal IORB] 
ARGUMENT DESCRIPTION: 


location of terminal IORB 


Any address form valid for a data register; provides 
the address of the input/output request block (IORB) 
of the terminal associated with this task group. 


FUNCTION DESCRIPTION: 


This call enables the task group of the issuing task to be 
notified when a terminal user logs in aS a Secondary user of 
the task group. Notification is made at the terminal asso- 
Ciated with the task group issuing the call. 


If a secondary user logs in after this call has been issued, 
the terminal from which the uSer logs in is reserved by the 
task group isSuing the call. The issuing task group can use 
the SRLTML macro call to release the terminal. The issuing 
task group can cancel the request by a SCANRQ macro call. 


The buffer address field of the terminal IORB specifies an 
area that is to receive some or all of the login parameters 
in the format specified below. (The actual amount of data 
transferred is determined by the IORB buffer range field.) 
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Word(s) 


13-18 


19-22 


23-xx 


Contents 


Terminal LRN 


Terminal symbolic peripheral device name 
(e.g., TTYO) 


Person identification from login line or 
the default account 


Account name for login line or the default 
account 


Encrypted password from login sequence 
(networking use only) 


Entire login line as entered from terminal 


The setting of the IROBs W-bit determines whether control is 
returned immediately or is returned after a login has 


occurred. 


The IROB's I/O bit must be set; the D-bit is reset. The S- 
and R-bits specify how the task group is to be notified when 
the request is satisfied. The requesting task group must 
issue a get file macro call to the terminal file to reserve 


the file. 


NOTES: 1 


The address of the terminal IORB supplied by 
argument 1 is placed in $B4; if this argument is 
omitted, SB4 is assumed to contain the current 
address. 


On return, SR1 contains one of the following 
return status codes: 


0000 - If no wait specified, request was issued 
successfully; if wait specified, success- 
ful login 

0817 —- Memory access violation 


0824 - Request canceled. 


O82E - Parameter error (invalid control bits in 
IORB) 


On return, SB4 contains the request block 
address. 


This macro call modifies item I CT2 of the IORB. 
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Example: 


In this example, the SROTML macro call is used to ensure 


that the issuing task group is notified when a terminal user 


logs in aS a secondary user of the task group. 


The informa- 


tion returned to the task group consists only of the termi- 
nal LRN, terminal symbolic peripheral device name, person 

identification, and account name. 
returned immediately to the issuing task group; the group 
does not wait for a login to 


CHK 1 SROTML 
* 
DEFINE IORB 
* 
IORB RESV 
TEXT 
TEXT 
DC 
DC 
DC 
DC 
DC 
* 
. END IORB 
* 
SEC_USR RESV 
IN LNG EQU 
* 


!TORB 


mm ™%O Ne MO Ne VE 


me 


=m %O WO 


=e 


212 os sc slUchtlrlUD —s— = 


18,0 


=e 


OCCULr. 


Note that control is 


RSU 

RETURN STATUS 
T-BIT (IN USE) 
W-BIT (DON'T WAIT) 
U=BIT (USER) 

MBZ 

MUST BE ONE 

LRN 

MBZ 

B-BIT (BYTE INDEX) 
MBZ 

FUNCTION CODE 
BUFFER ADDRESS 
RANGE 


RESIDUAL RANGE 
STATUS WORD 


2* (S$-SEC_USR) 
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RESERVE SEMAPHORE 


RESERVE SEMAPHORE 

Macro Call Name: SRSVSM 

Function Code: 06/02 

Equivalent Command: None 
Reserve a resource controlled by the specified semaphore if 
the resource is available (i.e., do a P-op or P-test). If 
the resource is not available, perform one of the following 
actions, depending on the value of argument 2: 
o Return immediately to the issuing task (do a P-test). 
o Suspend the issuing task until the resource becomes 

available. Then reserve the resource and return to the 


issuing task (these three actions are known collectively 
aS a P-op). | 


FORMAT: 


[label] SRSVSM [location of semaphore identifier], [Vert 


ARGUMENT DESCRIPTION: 

location of semaphore identifier 
Any address form valid for a data register; provides 
the two ASCII characters that identify the semaphore 


associated with the resource to be reserved. 


DENY 


Specifies that if the resource is not available for 
reservation, an immediate return to the issuing task 
is to be made (i.e., a P-test is to be done). 
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By 


WAIT 


Specifies that if the resource is not available for 
reservation, the issuing task is to be suspended until 
the resource becomes available; then the resource is 
to be reserved and a return to the issuing program is 
to be made (i.e., a P-op is to be done). 


WAIT is assumed if the argument is omitted. 
FUNCTION DESCRIPTION: 
This call is a synchronous request for a resource controlled 


by the semaphore identified in argument 1. This semaphore 
must have been defined by a define semaphore macro call. 


When a P-op is performed, the counter whose initial value 
was established by the define Semaphore macro call is 
decremented by l. 


Since the reserve function does not queue a Semaphore 

request block (see request semaphore macro call), the 

reserve resource macro call must be reissued when DENY is 

specified for argument 2. 

NOTES: 1. The Semaphore identifier supplied by argument 1] 
is placed in SR6; if this argument is omitted, 
SR6 is assumed to contain the identifier of the 
semaphore to be tested. 

2. If DENY was specified for argument 2, S$R2 is set 
to 0 (P-test to be done); if WAIT is specified 
for argument 2, or if the argument is omitted, 
SR2 is set to -l (P-op to be done). 


3. On return, $R1 and SR6 contain the following 
information: 


SR1 - Return status; one of the following: 
O000 - No error 


0501 - Unsuccessful reservation (only if 
DENY specified) 


0502 - Semaphore not defined 
0505 - Illegal return condition indicator 


SR6 -— Semaphore identifier (as supplied) 
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Examples: 


For an example of the reserve semaphore (SRSVSM) macro call 
see the example given for the define semaphore macro call. 
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RESET DEVICE ATTENTION 


RESET DEVICE ATTENTION (MOD 400 ONLY) 
Macro Call Name: SRDVAT 

Function Code: 02/03 

Equivalent Command: None 


Turn off the attention status indicator in the reSource 
control table (RCT) of the specified device. 


FORMAT: 


[label] SRDVAT [location of LRN] 
ARGUMENT DESCRIPTION: 


location of LRN 


Any address form valid for a data register; provides 
the LRN of the device whose attention status indicator 
is to be reset. The LRN must be a system LRN (defined 
at system building). 


FUNCTION DESCRIPTION: 


This call turns off the attention status indicator (bit 8 of 
the R_FLGS entry) in the RCT of the specified device. 

SRDVAT can be used in synchronizing task operation with 
device availability. 


A task can issue a disable device on attention macro call 
(SDSDV) to request notification of an interrupt. When the 
interrupt occurs, the device driver will set bit 10 (device 
disabled) and bit 8 (attention has occurred) of R_FLGS. 
When a ready interrupt is generated, the task can clear the 
disabled status by resetting bit 10 through the SENDV macro 
call. 
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After clearing bit 8, using the reset device attention 
(SRDVAT) macro call, and waiting for the device ready inter- 
rupt to occur, a task can use the enable device (SENDV) and 
the reset device attention (SRDVAT) macro calls to clear 
bits 8 and 10 to initial states. 


NOTES: 1. The LRN specified by argument 1 is placed in 
SR2; if this argument is omitted, $R2 is assumed 
to contain the correct LRN. 


2. On return, SR1 and SR2 contain the following 
information: | 


SR1 - Return status; one of the following: 


0000 -—- No error 
0102 - Invalid Error 


SR2 -—- LRN of the device 


Example: \ 


In this example, the SRDVAT macro call is used to turn off 
the attention status indicator in the RCT of the device 
whose LRN is 15. If the interrupt occurs, the device will 
be set to the disabled state. When a ready interrupt 
occurs, the device disabled condition is cleared through the 
SENDV (enable device) macro call. 


ATTOFF SRDVAT =15 


CLRDIS SENDV =15 
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RETURN 


RETURN 
Macro Call Name: SRETRN 
Function Code: None 


Equivalent Command: None 


Issues a Standard return sequence for tasks or called 
Subroutines. | 


FORMAT : 


[label] SRETRN [location of completion status], 
[location of return address] 


ARGUMENT DESCRIPTION: 
location of completion status 


Any address form valid for a data register; provides 
the user-selected status code to be returned when the 
subroutine or system service routine finishes pro- 
cessing. Any code can be selected. 


location of return address 


Any address form valid for an address register; pro- 
vides the address in the calling task to which the 
Subroutine or system service routine will return when 
it has finished processing. 


FUNCTION DESCRIPTION: 


This macro call allows a procedure (which can be called as a 
subroutine or invoked to service a task request) to have a 
common return interface to the calling task. 


If the procedure was Statically linked with its caller, the 
return address supplied in argument 2 is placed in S$B5 and a 
JMP SB5 instruction is issued. The completion status is 
placed in SRl. 
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If the procedure was invoked as a subtask, the procedure's 


task is terminated and its request block is marked as = 


complete. (See "Terminate Request" for further information 
about task termination.) 


Note that SB5 is set to the address of a system-Supplied 
termination routine when any of the following occur: 


o A task is initially activated to service a request. 
o A return request block macro call is issued. 


NOTES: 1. The status code specified by argument 1 is 
Placed in SR2; if this argument is omitted, SR2 
1S assumed to contain the intended status code. 


2. The address supplied by argument 2 is placed in 
SB5 and a JMP $B5 instruction is executed. If 
this argument is omitted, S$B5 is assumed to con- 
tain the return address. 


Example: 


In this example, the RETRN macro call is used by a Semaphore 
to return to its caller with a completion status of zero. 
The example assumes the procedure was entered at the entry 
pointed named BEGIN, and that the contents of SAV B5 are 

not altered within the procedure - other than at its entry 
point. If the procedure was statically linked with its 
caller, the macro call causes a JMP SB5 return to the 
caller, with the completion status in SRl. If the procedure 
was invoked as a subtask, the macro call causes the pro- 
cedure's task to be terminated and its request block marked 
as complete. 


_ EDEF BEGIN 
BEGIN STB $B5,SAV_B5 

SRETRN =0,SAV_B5 
SAV_B5 RESV 2 


S=3 12 CB08 


ene! 


RETURN MEMORY/RETURN 
PARTIAL BLOCK OF MEMORY 


RETURN MEMORY /RETURN PARTIAL BLOCK OF MEMORY 


Macro Call Name: SRM EM 


Function Code: 04/04 (return memory), 
04/05 (return partial block) 


Equivalent Comand: None 


Return all or part of the previously allocated memory block 
to the memory pool of the task group of the issuing task. 
If argument 2 is omitted, return all of the memory block; if 


argument 2 is specified, return the number of words it 
indicates. 


FORMAT : 


[label] SRMEM [location of memory block address], 
[location of number of words to be returned] 


ARGUMENT DESCRIPTION: 
location of memory block address 


Any address form valid for an address register; pro- 
vides the location of the address of the leftmost word 
(excluding the block header) of the memory block to be 
returned (either partially or totally). 


location of number of words to be returned 


Any address form valid for a data register; provides 
the number of words to be returned (Starting at the 

rightmost part of the block). If this parameter is 

omitted, the entire memory block is returned. 


FUNCTION DESCRIPTION: 


The return memory and return partial block of memory macro 
calls are the means by which a task returns a previously 
allocated memory block to the task group's memory area. If 
the entire block is to be returned, argument 2 is omitted. 
If a part of the block is to be returned, argument 2 speci- 
fies the number of words to be returned. 
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When a partial block of memory is returned, the return is 
done in 32-word increments of memory; the actual amount of 
memory returned is the specified amount rounded down to the 
next lower 32-word increment. 


The memory block address referred to by argument 1 is the 
same address as that returned in $B4 when the task issued a 
get memory or get available memory macro call and was allo- 
cated this block. 


NOTES: 1. 


The memory block address derived from argument 1 
is placed in $B4; if this argument is omitted, 
SB4 is assumed to contain the address of the 
memory block to be returned. 


The number of words to be returned (partial 
return only) derived from argument 2 is placed 
in $R6 and S$R7. If argument 2 is =$R7, it is 
assumed that S$R6 and $R7 contain the number of 
words to be returned. If argument 2 is omitted, 
the entire memory block is returned. 


On return, SR1l1, $R6, SR7, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 
0000 - No error 


0603 - Illegal memory block address 
specified 


0604 - Size of memory to be returned is 
greater than size of memory block 
(partial return only) 


0818 - No task group with specified group 
id exists (system software error) 


081B —- Roll-in of online task group 
attempted (system software error) 


O81C - Roll-in attempted when batch group 
not rolled out (system software 
error) 


O8l1E - Unrecoverable media error during 
roll-in 


O81F - Group not suspended when roll-in 
attempted (system software error) 
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SR6, SR7 - Partial return only; remaining size 
of block still allocated 


SB4 - Partial return only; address of first 
(leftmost) word of allocated meme” block 
(excluding header word). 


Examples: 


In this example, the SRMEM macro call is used to return all 
of the memory obtained in the first example for the get 
memory/get available memory macro calls. The SRMEM macro 
call is assumed to be contained in the same procedure as the 
coding shown in that example. 


SRMEM M PTR 


In this example, the SRMEM macro call is used to return 100 
words of the memory obtained in the first example for the 
get memory/get available memory macro calls. Upon return 
from the system $B4 will contain the address of the first 
usable word of the memory area and S$R6 and SR7 will specify 
the number of words still remaining in the memory area. The 
SRMEM macro call is assumed to be contained in the same pro- 
cedure as the coding shown in the get memory example. 


SRMEM M PTR,=100 
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RETURN REQUEST BLOCK ADDRESS 


RETURN REQUEST BLOCK ADDRESS 
Macro Call Name: SRBADD 
Function Code: 01/07 
Equivalent Command: None 


Return the address of the request block currently at the 
head (top) of the issuing task's request queue. 


FORMAT: 
[label] SRBADD 
ARGUMENT DESCRIPTION: 
No arguments are used with this call. 
FUNCTION DESCRIPTION: 
This call returns the Seabees of the first request block in 


the request queue for the task. The request block is not 
removed or altered. 


The address of the request block is placed in $B4. The 
address of the argument list (if any) associated with the 
request block is placed in S$B7. 


Upon return to the issuing task, $B5 contains the address of 
the system-supplied termination routine. 


NOTE: On return, SR1, $B4, $B5, and $B7 contain the fol- 
lowing information: 


SR1 - Return status; one of the following: 
0000 - No error 
0801 - No request block found (no dispatched 


request block exists for the issuing 
task) . 
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SB4 - Address of current request block (if $Rl is 
0000) 


SB5 - Address of system-supplied termination routine 


SB7 - Address of request block argument list (if SRl 
is 0000) 


Example: 


In this example, the SRBADD macro call returns the address 
of the issuing task's request block in $B4. The address of 
the argument list contained within the request block is 


returned in $B7 and the address of a system-Supplied termi- 
nation routine is returned in S$B5. 


CHEK L SRBADD 
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REWRITE RECORD 


REWRITE RECORD 


Macro Call Name: SRWREC 


Function Code: 11/40 (current), 11/41 (key) 


Equivalent Command: None 


| 


Change the contents of the specified logical record in the 
file; this macro call is valid for all file organizations 
except tape-resident sequential files and device files. 


FORMAT : 


— 
[label] $RWREC [fib address] bie | 


, KEY 


ARGUMENT DESCRIPTION: 


fib address 


Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). 


wees 


This mode argument indicates that the record read by 

the immediately preceding read next or read with key 

(i1.e., the last record read; see “Read Record") macro 
call is to be rewritten by the record defined in the 

FIB. This is the default value for this macro call. 

You must code the following FIB entries: 


logical file number 
user record pointer 
output record length 


This mode is referred to as rewrite current record. 
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( KEY 


This mode argument indicates that the position in the 
file associated with the key value specified in the 
FIB is to be written over by the record identified by 
the FIB. You must code the following FIB entries: 


logical file number 


input key pointer (unless this is an indexed 
file that contains the key embedded in the 
logical record) 


input key length 
This mode is referred to as rewrite with key. 


FUNCTION DESCRIPTION: 


Before this macro call can be executed, the file must have 
been opened (see the open file macro call) with a program 
view word that allows access via data management (bit 0 is 
0) and allows rewrite operations (bit 3 is 1). The file 
must have been reserved (see the get file call) with write 
acceSsS concurrency control (type 3, 4, or 5). The rewrite 

. record macro call has no effect on the read or write 

. pointer. If the file is an indexed file, the embedded key 
must not be altered. 


The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined by the 
STFIB macro call. 


NOTES: 1. If the first argument is coded, the address of 
the FIB is loaded into $B4; if this argument is 
omitted, SB4 is assumed to contain the address 
of the FIB. 


2. On return, SR1 contains one of the following 
status codes: 


QO00 - No error 

0203 - Illegal function 

0205 - Illegal argument 

0206 -— Unknown or illegal LFN 

0207 - LFN not open 

020A - Address out of file 

QO20E - Record not found 

0217 - Access violation 

O219 - No current record pointer 
ae | O21A - Record length error 
( O21D - Attempt to change the symbolic key value 
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QO21E - Key length or location error 
022A - Record lock area overflow or not defined 
022B - Requested record is locked 


In addition to the above codes, any system 
service codes received by ene data manager are 
passed on through SRl. 


Example: 
In this example, it is assumed that the file is reserved 
with write access concurrency control and opened. The FIB 
identified in the first parameter is defined in "Assumptions 
for File System Examples" in Section 3. The macro call is 

. specified as follows: 


BACREC SRWREC IMYFIB,CURRENT 
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SEMAPHORE REQUEST BLOCK 


SEMAPHORE REQUEST BLOCK 


Macro Call Name: S$SRB 
Function Code: None 
Equivalent Command: None 


Generate a semaphore request block whose length is four 
words in SAF mode and five words in LAF mode. 


FORMAT : 


[label] S$SRB [semaphore identifier], 
[issuing task suspension option], 


or 
[termination action] 
ARGUMENT DESCRIPTION: 
semaphore identifier 


A 2-character (ASCII) identifier that must have been 
defined by the task issuing the semaphore request. If 
this argument is omitted, the semaphore identifier is 
set to an initial value of zero. 


issuing task Suspension option 


One of the following values is specified to indicate 
whether the requesting task is to be suspended until 
the resource associated with the Semaphore becomes 
available: 


WAIT 


Suspend the issuing task until the resource 
becomes available (set w-bit to 0) 


NWAIT 
Do not suspend the issuing task (Set w-bit to 1) 


5-321 | CB08 


If this argument is omitted, the value NWAIT is 
assumed. | 


If WAIT is specified, argument 3 must be omitted. 


termination action 


One of the following values is specified to indicate 
the action to be taken when the resource becomes 
available to the issuing task: | 


SM=aa 


Do not suspend the isSuing task; release (V-op) 
the semaphore identified by aa (two ASCII char- 
acters) when requested task is completed. 


RB=label 


Do not suspend the issuing task; issue a request 
for the request block identified by label, when 
requested task is completed. 


If this argument is omitted (or argument 2 is WAIT), 
the generated SRB contains no termination option. 


FUNCTION DESCRIPTION: 


The semaphore request block (SRB) is used to request 
asynchronously the reservation of a resource controlled by 
the specified semaphore. The SRB contains a semaphore id 


which identifies the (previously defined) semaphore being 
requested. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 


Preparation manual for more information about SAF/LAF 
independent code. 


Example: 


In this example, the SSRB macro call generates a semaphore 
request block with identifier AA. The w-bit is set to zero 
to indicate the requesting task is to be suspended until the 
resource becomes available. No suspension action is given. 


GTRAA SS RB AA,WAIT 
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SEMAPHORE REQUEST BLOCK 
OFFSETS 


SEMAPHORE REQUEST BLOCK OFFSETS. (MOD 400 ONLY) 


Macro Call Name: SSRBD 


Counterpart: SSRB (See "Semaphore Request Block") 
Generated Label Prefixes: 


S RRB/S SEM 
SRB label offset 0 
S cTl 
S CT2 
S ADR 


See Appendix A for the format of the semaphore request 
block. 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 
independent code. 
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SET DIAL 


SET DIAL 
Macro Call Name: SSDL 


Function Code: 1B/00 


Equivalent Command: Set Autodial Telephone Number (SDL) 


Insert the specified telephone number into the first entry 
in the autodial telephone number list for the specified 
line. This telephone number will be used first when the 
autodial facility attempts to establish a connection on the 


(switched circuit) line. 

FORMAT 1: 

[label] SSDL [location of channel 
[location of address 
CHANNEL 

FORMAT 2: 

[label] SSDL [location of address 
[location of address 
[PATHNAME ] 

ARGUMENT DESCRIPTION: 


location of channel number 


Any address form valid for a 


number], | 
of telephone number], 


of device pathnamel, 
of telephone number], 


data register; provides 


the four hexadecimal digits that define the 10-bit 
channel number of the data line. The channel number 
must be stored left-justified with low-order zero 
Filling. (Applicable to format 1 only.) 
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location of address of telephone number 


Any address form valid for an address register; pro- 
vides the address of the telephone number to be asso- 
Ciated with the data line. The telephone number must 
be stored as an aligned, nonvarying, character string 
containing at least one trailing space and no embedded 
spaces. The telephone number can contain from 5 
through 16 ASCII characters chosen from the set 0, l, 
2, 35 45 Op Be Ty Bo. Oe Se RG (Applicable to formats 
1 and 2.) 


CHANNEL | 
CHAN 


Incicates that format 1 of the macro call is being 
used (channel number of line is provided). 


location of address of device pathname 


Any address form valid for an address register. For 
example, the device pathname could be >SPD>TTY1; see 
"Get File." The pathname must be stored as an 
aligned, nonvarying, character string containing at 
least one trailing space and no embedded spaces. 
(Applicable to format 2 only.) 


PATHNAME 
PATH 
Indicates that format 2 of the macro call is being 
used (pathname of line is provided). 


FUNCTION DESCRIPTION: 


During system building, you can specify that the communica- 
tions autodial facility be applied to one or more communica- 
tions lines. For each line that is to employ autodialing, 
you construct a list of telephone numbers. The first entry 
in this list is left empty by the system. The other entries 
are filled in according to your specifications. 


The $SDL macro call allows you to dynamically insert a 
telephone number into the first entry in the list for a 
Particular line. When the autodial handler is invoked, this 
telephone number will be dialed first in the attempt to 
establish a connection with the terminal(s) on the line. If 
no successful connection is established, the next entry 
(telephone number) in the list is dialed, and so on until a 
successful connection is made or every number in the list 
has been dialed. (Each telephone number is dialed three 
times at 40-second intervals.) 
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NOTES: 


Example: 


For format 1, the channel number Supplied by 
argument 1 is placed in SR6; if this argument is 
omitted, SR6 is assumed to contain the channel 
number. 


The format 2, SR6 is cleared to zero and the 
address of the device pathname supplied by argu- 
ment 1 is placed in $B2. If argument 1 is 
omitted, $B2 is assumed to contain the address 
of the device pathname. 


For formats 1 and 2, the address of the tele- 
phone number supplied by argument 2 is placed in 
SB4; if this argument is omitted, $B4 is assumed 
to contain the address of the telephone number. 
For format 1, CHANNEL (or CHAN) must be coded. 
For format 2, all three arguments can be 
omitted. If this is done, SR6 is assumed to 
contain zeros, $B2 is assumed to contain the 
address of the device pathname, and S$B4 is 


assumed to contain the address of the telephone 
number. 


On return, SR1 contains one of the following 
status codes: 


0000 - No error 
0201 -— Illegal pathname 
0701 - Channel not configured 


0702 - Autodial control unit not configured on 
this channel 


0703 - ACU in progress 
1704 - Illegal argument length 


170F - Invalid digit in telephone number 


In this example, the terminal whose pathname is >SPD>TTY1 is 
to be automatically dialed using the number 1-617-555-4444. 
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DIALAA 


PTNM 
NUM 12 


SSDL 


!PTNM,!NUM_ 12, PATH 


'>SPD>TTY1 A’ 
"16175554444A! 


Seo 
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SET EXTERNAL SWITCHES 


SET EXTERNAL SWITCHES 
Macro Call Name: -SSETSW 


Function Code: 0OB/01 
Equivalent Command: Modify External Switches (MSW) 


set the specified external switches in the task group's 


external switch word to on; return the inclusive logical OR 
of the previous settings. 


FORMAT: 


[label] SSETSW external switch name, 
[external switch name], 


[external switch name] 


ARGUMENT DESCRIPTION: 
external switch name ... external switch name 


A single hexadecimal digit (0 through F) specifying 
the external switch in the task group's external 
Switch word. A maximum of 16 external switches (0 
through F) can be specified. If no arguments are sup- 
plied, $R2 is assumed to contain a mask word specify- 
ing the switches to be set on. If ALL is specified, 
all external switches are set on. 


FUNCTION DESCRIPTION: 


This call provides a mask by which switches can be set in 
the external switch word of the issuing task's task group. 


It also provides an indication of the previous settings of 
these switches. 
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SR2 is the mask word. Each bit in $R2 that is 1 causes the 
corresponding bit in the external Switch word to be set on; 
each bit that is 0 causes the corresponding bit to remain 
unchanged. 


When the SSETSW macro call is executed, SR2 contains the new 
settings of the external switch word. Bit 11 (bit-test 
indicator) of the I-register provides an indication of the 
previous setting of the switches in the switch word, as 
follows: 


o If bit 11 is 0, no switch set on had previously been set 
on. 


o If bit 11 is 1, at least one switch of those set on had 
previously been set on. 


NOTES: 1. The bits corresponding to the external switches 
in the arguments are set on in $R2; if no argu- 
ments are supplied, SR2 is assumed to contain 
the mask to be used. If ALL is specified, all 
bits are set on in SR2. 


2. On return, S$R2 and the I-register contain the 
following information: 


SR2 - External switch word after modification 


I-register (Bit 11) - Inclusive OR of previous 
settings of switches set on: 


O — No switch set on was on 


1 - At least one switch of those set on was 
on 


Example: 
In this example, the SSETSW macro call is used to turn on 
external switches 2, 4, and B of the task group in which the 


issuing task is executing. % 


SET AA SSETSW 2,4,8B 
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SET TERMINAL CHARACTERISTICS 


SET TERMINAL CHARACTERISTICS 
Macro Call Name: SSTTY 
: Function Code: 10/45 
Equivalent Command: Set Terminal Characteristics (STTY) 
Set the file characteristics of a terminal. 
FORMAT: 
[label] SSTTY [location of parameter structure address] 
ARGUMENT DESCRIPTION: 
location of parameter structure address 


Any address form valid for an address register; the 
format of the parameter structure is: 


Word Field | Content 
0-2 s ympd Symbolic peripheral device name of 
* the terminal to be affected. 
3 line length Binary integer specifying the line 


length (not including the slew 
byte) of the terminal. If this 
word is zero, the terminal's line 
length is not changed. 


4 dev i#e- An aligned 16-bit string that 


Specific specifies the device specific word. 
word If all zero bits, the terminal 


device-specific word is not 
changed. (See the Communications 
Processing manual for possible 
values.) | 
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Word Field Content 


5 file An aligned 16-bit string that 
indicator specifies the characteristics of 
the terminal to be changed (0 
means do not change the character- 
istic; 1 means change the 
characteristic). 


Bit Meaning 

0 Input-only device type 

1 Output-only device type 

2 Bidirectional device type 

3 Detab on 

4 Detab off 

5 Asynchronous input 

6 Asynchronous output 

7 Synchronous input 

8 Synchronous output 

9 Synchronous nonbuffered input 
10 Synchronous nonbuffered 

output 


11-15 Must be zero 


The device type (bits 0, 1, and 2) 
cannot be changed if the file is 
open. 


6-16 Reserved for later use 
FUNCTION DESCRIPTION: 


This call allows the issuing task to dynamically alter 
terminal file characteristics. The original file character- 
istics, established at system generation, can be altered to 
reflect the needs of the issuing task. 


NOTES: 1. The address of the parameter structure supplied 
by argument 1 is placed in $B4; if this argument 
is omitted, $B4 is assumed to contain the 
address. 


5554  CB08 


2. On return, $R1 contains one of the following 
Status codes: 


rs 


0000 -—- No error 


1302 —- Device name not found 
1304 - Parameter missing or incomplete 
1306 - Parameter not consistent with device type 


Example: 


In this example, the terminal whose symbolic peripheral 
device name is TTY4 is changed to an output-only device for 
asynchronous output. Neither the line length nor the 
device-specific word is changed. (It is assumed that the 
file is not open.) 


TER AA DC 'TTY4AA' 
RESV 2,0 
DC B'0100001000000000 ' 
SETAA SSTTY  !TER_AA 
| (10) z'0000' 
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SPAWN GROUP 


SPAWN GROUP 


Macro Call Name: SSPGRP 


Function Code: 0D/05 


Equivalent Command: Spawn Group (SG) 


Create the definition of a new task group within the system. 
Request the execution of the group's lead task. Delete the 
group from the system when the group request terminates. 


FORMAT: 


[label] 


SSPGRP [location of group identifier], 


[location of address of argument list], 
[location of address of fixed parameter block], 
[location of memory pool identifier], 

[location of base level], 

[location of high logical resource number], 
[location of high logical file number], 
[location of root entry name address] 


ARGUMENT DESCRIPTION: 


location of group identifier 


Any address form valid for a data register; provides 
the group identification of the task group to be 
Spawned. The group identification must be a two- 
character (ASCII) name that does not have the §$ 
character as its first character. 


location of address of argument list 


Any address form valid for an address register; pro- 
vides the address of the argument list, which can be 
generated by the parameter block macro call to be used 
to specialize a request block that will be used. to 
request the lead task of the spawned task group. 


5553 CB08 


location of address of fixed parameter block 


Any address form valid for an address register; pro- 
vides the address of a fixed parameter block, which 
‘can be generated by the parameter block macro call. 
This parameter block has the following arguments: 


Argument l 


A string specifying the user id to be asSociated 
with the spawned task group (for system use). 

If this entry is zero, the user id currently 
associated with the issuing task group will be 
used when the call is executed from a user task 
group. 


Argument 2 


A pathname string specifying the command-in and 
initial user-in files for this request of the 
lead task of the spawned task group. If this 
entry is zero, no command-in and initial user-in 
files will be available to the spawned group. 
However, the spawned group can later obtain a 
user-in file by means of the new user input 
macro call. A nonzero entry is required if the 
command processor is the lead task. 


Argument 3 


A pathname string specifying the error-out and 
initial user-out files of the spawned task 
group. If this entry is zero, one of the fol- 
lowing assumptions is made when the call is 
executed: 


o If the pathname string specifying the 
command-in and initial user-in files (in- 
path) specifies a disk device, the pathname 
for the output files is in-path.A0O. 


o If in-path specifies an interactive terminal, 
the pathname for the output files is the same 
aS in-path. 


o If in-path specifies an input-only device, 
the pathname for the output files is null. 


Argument 4 
A pathname string specifying the initial value 
of the working directory to be used ey the pS 
spawned task group. Me 
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location of memory pool identifier 


Any address form valid for a data register; provides 
the identifier of the memory pool to be used to 
service all memory requests emanating from the spawned 
task group. The memory pool identifier consists of 
two ASCII characters that name a pool defined at 
system generation. If this argument is omitted, the 
spawned task group will use the memory pool associated 
with the issuing task group. 


location of base level 


Any address form valid for a data register; provides 
the base priority level, relative to the system level, 
at which the lead task will execute. 


A base level of 0, if specified, is the next higher 
level above the last system priority level. The sum 
of the highest system physical level plus 1, and the 
base level of a group, and the relative level of a 
task within that group, must not exceed 62 . 


location of high logical resource number 


Any address form valid for a data register; Specifies 
the highest logical resource number (LRN) that will be 
used by any task in the spawned task group. The LRN 
can be a value from 0 through FF (hexadecimal). If 
this argument is omitted, or if the value specified is 
less than the highest LRN used by the system task 
group, the system task group's LRN will be used. 


location of high logical file number 


Any address form valid for a data register; Specifies 
the highest logical file number (LFN) to be used by 
any task in the spawned task group. The LFN can be a 
value from 0 through FF (hexadecimal). If this argu- 
ment is omitted, the value 15 is assumed. (Refer to 
the associate file macro call.) 
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location of root entry name address 


Any address form valid for an address register; pro- 
vides the address of the root entry name string that 
specifies the pathname of the bound unit to be exe- 
cuted as the lead task of the spawned group. The 
bound unit pathname can have an optional suffix in the 
form of ?Pentry, where entry is the symbolic start 
address within the root segment. If this suffix is 
not given, the default start address (established at 
assembly or link time) is used. For example, to 
Specify the command processor as the lead task, use 
the pathname EC?ECL. 


FUNCTION DESCRIPTION: 


This call combines the create group, enter group request, 
and delete group macro calls. Spawn group implicitly causes 
the execution of these calls in sequence (i.e., it (1) allo- 
cates and creates the data structures required to define and 
control the execution of the task group, (2) places a 
request against the group, thereby activating it and, (3) 
when execution terminates, removes all controlling data 
structures and returns memory used by the task group to the 
appropriate memory pool). 


Spawned task groups cannot be requested, nor can they be 
waited upon. 


The request block generated according to the second argument 
in the macro call is constructed in space taken from the 
memory pool of the spawned task group. 


A spawn group macro call can be issued from a task group 
that was itself spawned. 


NOTES: 1. The group identifier specified by argument 1 is 
placed in SR2; if this argument is omitted, $R2 
is assumed to contain the group id to be used. 


2. The address of the argument 1ist Supplied by 
argument 2 is placed in S$B4; if this argument is 
omitted, $B4 is assumed to contain the address 
of the argument list to be used to build the 
request block. 


3. The address of the fixed parameter block sup- 
plied by argument 3 is placed in S$B5; if this 
argument is omitted, $B5 is assumed to contain 
the address of the block to be used. 
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The memory pool identifier specified by argument 
4 is placed in SR4; if this argument is omitted, 
SR4 is set to zero to indicate that the memory 
pool of the issuing task group is to be used by 
the spawned task group. 


The base priority level specified by argument 5 
is placed in $R5; if this argument is omitted, 
SR5 is assumed to contain the base priority 
level to be used. 


The high LRN value specified by argument 6 is 
placed in $R6; if argument 6 is omitted, SR6 is 
set to zero to indicate that the value of the 
highest LRN created for the system task group 
will be used. 


The high LFN value specified by argument 7 is 
placed in $R7; if this argument is omitted, S$R7 
is: Set. to 15. 


The address of the root entry name Supplied by 
argument 8 is placed in $B2; if this argument is 
omitted, S$B2 is assumed to contain the address 
of the root entry name of the bound unit to be 
executed by the lead task of the spawned group. 


On return, SR1 and $R2 contain the following 
information: 


SR1 - Return status; one of the following: 


0000 No error 

0601 Insufficient memory 

0602 Insufficient memory 

0804 Group id in use 

0806 Invalid group id 

0807 Invalid memory pool identifier 
0808 Invalid base level 

0809 Invalid high LRN 

O80A Invalid high LFN 

O80C Unresolved start address 
160A Invalid pathname 

160B Insufficient memory 


SR2 - Group id of spawned task group 


5-337 CBO08 


Example: 


In this example, the SSPGRP macro call is used to create a 
task group, execute a task in that group, and then delete 
the group. The task group is created with a group id of Q2, 
use of memory pool P2, and a base level of 40 (decimal). 
Both the high LRN and the high LFN are defaulted (only 
system logical resources will be available and the highest 
logical file number available will be 15, decimal). The 
task group's lead task will be the command processor. The 
request part of the spawn is the same as the request given 
in the example for the request group macro call. 


SSPGRP ='92',!ARGS,!INFO; 
='p2',=40,, ,} ROOT 


INFO SPRBLK ,°V1124>UDD>TEST>JONES>ASM TST; 
“V1124>UDD>TEST>JONES>L>ASM TST.AQ; 
: “V1124>UDD>TEST >JONES ~ 
ARGS SPRBLK ~XREF,-PRINT 
ROOT TEXT "EC? ZXECLA! 
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SPAWN TASK 


SPAWN TASK 
Macro Call Name: SSPTSK 


Function Code: O0C/05 (different bound unit), 
CC/0O6 (same bound unit) 


Equivalent Command: Spawn Task (ST) 


Create, request the execution of, and then cause a task to 
be deleted within the task group of the issuing task. 


FORMAT: 


[label] SSPTSK [location of task request block address], 
[location of relative priority level], 
[location of start address], 
[location of root entry name address] 


ARGUMENT DESCRIPTION: 
location of task request block address 


Any address form valid for an address register; pro- 
vides the location of the address of the request block 
for the spawned task. The request block indicates 
whether the issuing task is to wait for the execution 
of the spawned task; the request block may contain 
parameters to be passed to the spawned task. 


location of relative priority level 


Any address form valid for a data register; provides 
the location of the priority level, relative to the 
task group's priority level, at which the spawned task 
is to execute. If this argument is omitted, the 
Priority level used is that of the issuing task. 
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location of start address 


Any address form valid for an address register; pro- 
vides the location of the task start address to be 
used when the spawned task is to execute the same 
bound unit as the issuing task. Note that the bound 
unit must have been declared sharable at the time it 
was linked. (Function code OC/06.) 


location of root entry name address 


Any address form valid for an address register; pro- 
vides the location of the address of the pathname of 
the bound unit root segment to be loaded for execution 
by the newly created task. The bound unit pathname 
can have an optional suffix in the form ?Pentry, where 
entry is the symbolic start address within the root 
segment. If no suffix is given, the default start 
address (established at Link time) is used. (Function 
code 0C/05.) 


FUNCTION DESCRIPTION: 


This call combines the functions of the create task, request 
task, and delete task macro calls in that it constructs the 
requisite structures for the execution of the task, acti- 
vates the task, and, when the task becomes inactive, deletes 
the task. When the spawned task is deleted, its associated 
data structures are removed and the memory they occupied is 
returned to the task group's memory pool. 


A spawned task iS not asSigned a logical resource number 
(LRN); therefore, the spawned task is local to the spawning 
task (1.e., is visible only to the spawning task). A 
Spawned task cannot be requested or referred to by any other 
task; nor can itS memory Space or code be shared. However, 
a spawned task can Share the memory Space and code of 
another task that was assigned an LRN by a previously issued 
Create task macro call. This sharing is indicated by the 
presence of argument 3. 


Either the location of the start address or the location of 
the root entry name address, but not both, can be specified. 


Multiple task requests can be made to execute concurrently 
within a given task's bound unit; this is accomplished by 
the issuing of multiple spawn task macro calls. 


NOTES: 1. The address of the request block supplied by 
argument 1 is placed in SB4; if this argument is 
omitted, $B4 is assumed to contain the address 
of the request block. 
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The relative priority level supplied by argument 
2 is placed in SR6; if this argument is omitted, 
SR6 is set to -1 to indicate that the priority 
level of the issuing task is to be used. 
Arguments 3 and 4 are mutually exclusive; if 
both are supplied, argument 3 is used and a 
diagnostic is issued. Information derived from 
either argument is placed in $B2; if these argu- 
ments are omitted, SB2 is assumed to contain the 
Start address within the bound unit. 


On return, SR1 contains one of the following 
status codes: 


0000 - Task successfully spawned (if no wait 
condition was indicated in the request 
block) 


OOOO-FFFF - Posted completion status of spawned 
task (if wait condition specified) 


Olxx - Media error 

0209 - Bound unit not found 

0602 - Insufficient memory 

O801 - Request block in use (t-—bit on) 

0817 - Access violation on request block 

0827 - Bound unit is not a fixed-relative file 
1604 - Unresolved symbolic start address 

160A - Insufficient memory 


1613 - Invalid bound unit pathname 


1614 - Access violation (root segment not user 
segment) 
1615 - Invalid bound unit file (header incorrect 


or number of overlays plus the root is 
equal to zero). 
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Example: 


In this example, the SSPTSK macro call creates a task, 
requests its execution, and then deletes the task. The task 
creation part of the spawn is the same as that given in the 
first example for the create task macro call, except that 
there is no LRN. The request part of the spawn is the same 
as that given in the example for the request task macro 
call, except that a synchronous request is made instead of 
an asynchronous request and no semaphore iS V-oped (see 
"Semaphore Functions" in Section 2). The delete part of the 


Spawn is the same as given in the example for the delete 
task macro call. 


SSPTSK !'TRB, =2,,!ROOT 


TRB STRB yer ENTRY.3,,-PRINT 
ROOT TEXT "PROG1O A! 
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STATUS MEMORY POOL 


STATUS MEMORY POOL 


Macro Call Name: SSTMP 
Function Code: 04/06 
Equivalent Command: None 


Determine the amount of memory available in a specified 
memory pool. 


FORMAT: 

[label] SSTMP [location of memory pool id] 
ARGUMENT DESCRIPTION: 
location of memory pool id 


Any address form valid for a data register; provides 
the memory pool id of the memory pool to be examined. 
If this argument is omitted, the memory pool examined 
is that associated with the task group of the isSuing 
task. 


FUNCTION DESCRIPTION: 


This call allows the issuing task to determine the amount of 
memory currently available in a specified memory pool. The 
amount of available memory is returned to the issuing task 
both as the actual number of words now available in the pool 
and as the percentage of the pool's total memory now avail- 
able. The total available memory may not be contiguous. 


If the memory pool being examined has the preempt batch 
option, the statistics returned are for the specified memory 
pool combined with the batch task group's memory pool. 


NOTES: 1. The memory pool id of the memory pool to be 
examined, supplied by argument 1, is placed in 
SR2; if this argument is omitted, $R2 is set to 
-l to indicate that the memory pool of the task 
group of the issuing task is to be examined. 
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2. On return, SR1, S$R2, SR6, and SR7 contain the 
following information: 


S$R1 —- Return 


0000 - 
0606 - 


SR2 - If SR1 
pool's 


Status; one of the following: 


No error | 
Illegal or undefined memory pool id 


is 0000, percentage of the memory 
total memory that is currently 


available. The percentage is returned as 
an integer with the fractional value 
truncated. 


SR6, SR7 - If SR1 is 0000, the number of words 
of memory currently available in the 


memory 


Example: 


pool. 


In this example, the S$STMP macro call is used to determine 
the amount of memory available in the memory pool of the 
issuing task's task group. The number of words of memory 


available in the pool is 


returned in S$R6 and SR7. A double- 


word 2500 is subtracted from the double word size, and the 
high-order word of the result is checked if the result is 


still positive. 


POOLCT SSTMP 
SUB SR7 = 2500 
BCT >+SA 
ADV SR6 -] 
SA BGEZ SR6,SOMMEM 
SOMMEM SGMEM =2500 
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SUSPEND GROUP 


SUSPEND GROUP 
Macro Call Name: SSUSPG 
Function Code: O0OD/08 
Equivalent Command: Suspend Group (SSPG) 
Suspend the specified task group. 
FORMAT : 
[label] SSUSPG flocation of group id] 
ARGUMENT DESCRIPTION: 
location of group id 
Any address form valid for a data register; provides 
the group id of the task group to be suspended. This 
task group must have been previously defined by a 


Create group macro call. 


FUNCTION DESCRIPTION: 


This call causes the system to Suspend the specified task 
group. The task group is marked as suspended when: 


o All tasks of the group have exited from critical areas of 
the Monitor. 


Oo All active task control blocks have been removed from 
their level queue. 


Oo All external requests (system driver, clock, memory, 
semaphore) have been satisfied. | 


A suspended task group can be activated through the SACTVG 
macro call. 


If the group id argument is $B, the SSUSPG macro call forces 
the rollout of the current batch task group. Rollin cannot 
occur until the SACTVG SB macro call is issued. 
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If the suspended task group is aborted, or if no other task 
group issues a SACTVG macro call to enable the suspended 
group, the operator must issue an ACTB or ACTG command to 
allow the suspended group to continue. 


NOTES: 1. The group id of the task group to be suspended, 
supplied by argument 1, is placed in SR2; if 
this argument is omitted, $R2 is assumed to con- 
tain the correct group id. 


2. On return, $R1 and $R2 contain the following 
information: 


SR1 - Return status; one of the following: 
0000 - No error 


0806 - Specified group id not currently 
defined 


SR2 - Group id as supplied 
Example: 
In this example, the SSUSPG macro call is used to suspend 


the task group whose group id is Gl. Task group Gl will not 
be suspended until all its tasks have exited from critical 


areas of the Monitor and all external requests have been 
satisfied. 


SUSGAA SS US PG =G l 
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( SUSPEND FOR INTERVAL 


SUSPEND FOR INTERVAL 
Macro Call Name: SSUSPN 
Function Code: (5/02 
Equivalent Command: None 


Remove the issuing task from the active queue for its 
priority level until the specified interval has elapsed. 


FORMAT: 


[label] SSUSPN interval unit designator, 
[location of interval value] 


ARGUMENT DESCRIPTION: 


ee 


interval unit designator 


Cne of the following codes must be specified to indi- 
cate the manner in which the interval is to be 
measured. 


Code Interval Measurement 
MS Milliseconds 

T Tenths of a second 

S Seconds 

M Minutes 

C Clock resolution units 


location of interval value 


Provides the interval for which the issuing task is to 
be suspended; can be one of the following: 


=SR7 


Interval value is in $R6 and SR7 
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=hexadecimal string 


String specifies the interval value 


fieldname 


fieldname represents the first word of a 2-word 
field containing the interval value 


FUNCTION DESCRIPTION: 


This call causes the issuing task to be suspended for the 
period of time specified in the call arguments. 


The suspend until time macro call (SSUSPN, function code 
05/03) also suspends the issuing task, but the Suspension 
exists until a particular date/time is reached. 


NOTES: 1. The interval unit designator supplied by argu- 
ment 1 is placed in $R2. The contents of $R2 


depend on the interval designator chosen, as 
follows: 


Interval 
Unit Contents 
Designator of SR2 


MS 
ar 


1 & WN FR 


S 
M 
C 


2. The interval value supplied by argument 2 is 
placed in SR6 and SR7; if this argument is 
omitted, or is =SR7, it is assumed that SR6 and 
SR7 contain the correct interval value. 


3. On return, $R1 contains one of the following 
return Status codes: 


0000 - Specified time has elapsed 
0401 - Invalid time interval specified 


4. Periodic use of this call by central processor 
bound tasks will allow other tasks with the same 
hardware priority level to obtain CPU time more 
often. 
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atm, 


&ed. ny 


Example: 


In this example, the $SUSPN macro call suspends the issuing 


task for one unit of time measured in units of clock 
resolution. 


ASTPA SSUSPN C,=l 
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SUSPEND UNTIL TIME 


SUSPEND UNTIL TIME 

Macro Call Name: S$SUSPN 
Function Code: 05/03 
Equivalent Command: None 


Remove the issuing task from the active queue for its 
priority level until the date/time specified in the call. 


FORMAT : 


[label] SSUSPN [TIME], 
[location of internal date/time value] 


ARGUMENT DESCRIPTION: 


TIME 


Optional keyword; explicitly notes that date/time 
value will be used to govern the suspension of the 
issuing task. 


location of internal date/time value 


Any address form valid for an address register; pro- 
vides the address of a 3-word internal date/time value 
until which the task is to be suspended. The value is 
a binary count of milliseconds since January 1, 1901. 


FUNCTION DESCRIPTION: 


This call causes the issuing task to be suspended until the 
date/time value indicated by argument 2 is reached. 


The suspend for interval macro call (S$SUSPN, function code 


05/02) also suspends the issuing task, but for a particular 
interval of time. 


NOTES: 1. If argument 1 is omitted, date/time format is 
assumed. 
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2. The internal date/time value supplied by argu- 
ment 2 is placed in S$R2, S$R6, and SR7. If this 
argument is omitted, or is either =SR2 or =SR7, 
these registers are assumed to contain the cor- 
rect internal date/time value. 


3. On return, SR1l contains one of the following 
status codes: 


0000 - Specified date/time has been reached 
0401 - Invalid internal date/time value 


Example: 


The get date/time macro call SGDTM is used to get the cur- 
rent date/time (in internal format), leaving it in registers 
SR2, SR6, and $R7. The convert to external date/time macro 
call (SEXDTM) is then used to convert this internal format 
to an external format, replacing the date portion (first ten 
characters) of the field labeled TODAY. The convert to 
external time macro call (SEXTIM) is then used to convert 
the internal format date/time to an external format, storing 
the hour of the day in the field labeled HOUR. The convert 
to internal date/time macro call (SINDTM) converts the con- 
tents of the field TODAY back to internal format contained 
in SR2, SR6, and SR7. The field HOUR is then compared to 
the constant 08. If HOUR is greater than or equal to 08, 
one day (86,400,000 milliseconds) is added to SR2, S$R6, and 
SR7. Thus S$R2, SR6, and $R7 now contain the internal format 
date/time value for the next time, either today or tomorrow, 
that 0800 hours will occur. The suspend until time macro 
call (SSUSPN) then suspends the issuing task until the next 
time the clock reads 0800 hours. The addition of one day to 
SR2, SR6, and $R7 is programmed assuming a central processor 
that has the add integer double (AID) instruction. (See the 
example given for the convert to internal date/time macro 
call for the same addition performed without the use of the 
AID instruction.) 
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SUS PND 


TODAY 
HOUR 
A_DAY 


GET THE CURRENT DATE/TIME VALUE. 
SGDTM 

CONVERT IT TO AN EXTERNAL FORMAT DATE. 
SEXTDT ,! TODAY, =10 

CONVERT IT TO AN EXTERNAL FORMAT HOUR OF DAY. 
SEXTIM , ! HOUR, =2 


NOW CONVERT THE EXTERNAL FORMAT DATE/TIME 
BACK TO THE INTERNAL FORMAT. 


SINDTM !TODAY, ,=15 


IF ITS BEFORE 0800 HOURS THE INTERNAL FORMAT 
DATE/TIME IS CORRECT ELSE ITS ONE DAY TOO SMALL. 


LDR $R1,HOUR 
CMR SR1,='08' 
BL >SUS PND 
AID A_DAY 
CAD =SR2 


SSUS PN TIME 


TEXT "YYYY/MM/DD 0800! 
TEXT "HH! 
DC 86400000B (31,0) 
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SYSTEM IDENTIFICATION 


SYSTEM IDENTIFICATION 


Macro Call Name: SSYSID 
Function Code: 14/04 
Equivalent Command: None 


Returns the identification of the system under which this 
task is running to a receiving field. The format of the 
receiving field is one word containing the number of charac- 
ters in the system id, followed by 15 words containing the 
system id itself. 


FORMAT : 


[label] SSYSID [location of system id field address] 
ARGUMENT DESCRIPTION: 
location of system id field address 


Any address form valid for an address register; pro- 
vides the address of a 30-character, aligned, varying 
receiving field into which the system will place the 
system identification. 


FUNCTION DESCRIPTION: 


This call returns the system id to a field in the issuing 
task. The system id is in the form: 


GCOS6/MOD 400-rrrr-mm/dd/hh/mm 


where rrrr is the system software release number and 
mm/dd/hh/mm are the date and time that the Monitor was 
linked. 


NOTES: 1. The address of the receiving system id field 
supplied by argument 1 is placed in S$B4; if this 
argument is omitted, $B4 is assumed to contain 
the address of the field. 
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2. On return, SR1 contains following status code: 


0000 -— No error 
0817 - Memory access violation 


Example: 


In this example, the SSYSID macro call is used to return the 


identification of the currently executing system to a field 
whose address is SYIDFL. 


ASYSID SS YSID ISYIDFL 


SYIDFL RESV 15,A'AA' 
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TASK GROUP INPUT 


TASK GROUP INPUT 

Macro Call Name: STGIN 
Function Code: 14/0C 
Equivalent Command: None 


Returns the pathname of the initial command-in file of the 
calling task group. 


FORMAT: 


[label] STGIN [location of task group input address] 
ARGUMENT DESCRIPTION: 


location of task group input address 


Any address form valid for an address register; pro- 
vides the address of a 58-character, aligned, non- 


varying field into which the system will place the 
pathname. 


FUNCTION DESCRIPTION: 


This macro call returns the pathname of the initial command- 
in file of the calling task group into a 58-character, 


aligned, nonvarying field whose address is provided by 
argument l. 


NOTES: 1. When the argument is entered, the task group 
input address is loaded into $B4. When the 
argument is omitted, S$SB4 is assumed to contain 


the address of the receiving home directory 
field. 


2. On return, SR1 and S$B4 contain the following 
information: 
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SR1 - Return Status; one of the following: 


0000 - No error | 
0817 - Memory access violation 


SB4 - Address of the receiving task group 
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( TASK REQUEST BLOCK 


TASK REQUEST BLOCK 

Macro Call Name: STRB 
Function Code: None 
Equivalent Command: None 


Generate a task request block (TRB) whose length is 
variable. 


FORMAT: 


[label] S$TRB [logical resource number], 
[issuing task suspension option], 


Or 


[termination option], 

[task start address], 

[size of request block argument], 
[user argument 1], 

[user argument 2], 


[user argument n] 
ARGUMENT DESCRIPTION: 
logical resource number 
A value from 0 through 252 specifying the LRN for this 
task. If this argument is omitted, the task request 
block does not have an LRN. 
issuing task suspension option 
One of the following values is specified to indicate 


whether the requesting task is to be suspended until 
the completion of the request: 
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NP 


NA 
“Pp 


WAIT 


Suspend the issuing task until the request is 
complete (Set w-bit to 0). 


NWAIT 


Do not suspend the issuing task (Set w-bit 
to. 1). 


If this argument is omitted, the value NWAIT is 
assumed. 


If WAIT is specified, argument 3 must be omitted. 


termination option 


One of the following values is specified to indicate 


the action to be taken upon the completion of the 
request. 


SM=aa 
Release (V-op) the semaphore identified by aa 
(two ASCII characters), when requested task is 
completed. 

RB=label 


Issue a request for the request block identified 
by label, when requested task is completed. 


If this argument is omitted (or argument 2 is WAIT), 


the generated task request block contains no termina-— 
tion option. 


task start address 


Any address form valid for an address register; pro- 
vides the start address to be used when the requested 
task is turned on to service the request. If this 
argument is omitted, the implicit task start address 


is to be used (bit 15 of the T_CTl word is set to 1; 
see Appendix A). 
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Size of argument to request block 


Value specifying the number of words in the added por- 
tion of the task request block. If this argument is 
omitted, the generated request block will be large 
enough to contain only the user arguments specified in 
the macro call. If no user arguments are specified, 
the request block will be generated to contain only 
the standard fixed format request block fields (argu- 
ments 1 through 4). If this argument is specified in 
addition to user arguments, an area is reserved fol- 
lowing those arguments. 


user argument 1... user argument n 
Begins the optional, variable-sized area containing 
user arguments to be passed to the requested task in 
response to a spawn task or request task macro call or 
command. This variable portion of the task request 
block is built in the following standard format. 


entry 1 - One-word count of number of argument 
pointers 


entry 2 - Address of first argument length field 


entry 3 - Address of second argument length field 


entry n -— Address of nth argument length field 


entry z - Length (in bytes) of first argument (one 
word) 


entry y - First argument value (of specified size) 


entry x - Length (in bytes) of second argument (one 
word) 


entry w - Second argument value (of specified size) 


entry p - Length (in bytes) of nth argument (one word) 


entry o - nth argument value (of specified size) 
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FUNCTION DESCRIPTION: 


The task request block is used to communicate between tasks. 
It serves as the means by which arguments are passed between 
the requested and requesting tasks within a task group. 

When a previously created task is requested, the task 
request block contains the LRN (logical resource number) 
that identifies the requested task. When a task is Spawned, 
the TRB does not require an LRN. 


The task request block may contain the start address to be 
used when the requested task is turned on to service the 
request. ' 


The task request block may contain a variable size portion 
that contains optional information to be passed to the 
requested task, and has a fixed size portion that contains 
Standard control information. 


When a task is activated, its $B4 register points to offset 
O of the request block and its S$B7 register points to a 
parameter list (if one is expected by the task). The proper 
SB7 address is established by the STRB macro call when it 
has a parameter list pointer, or by placing that pointer at 
the STRBD macro call's T PRM offset. 


Any task specific arguments are permitted (as if the TRB had 
been constructed by the command processor). 


NOTE: This macro call cannot be used in programs written in 
SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 
independent code. 


Example: 


In this example, the STRB macro call is used to create a 
task request block that has a 10-word argument (in addition 
to space added) to accommodate the parameters passed to the 
task in control arguments when the task is requested. The 
generated request block will be 18 words long, have an LRN 
of 30, and, when its task terminates, will release semaphore 
AA. | 


ATRBA STRB 30, ,SM=AA,,5,X 
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TASK REQUEST BLOCK 
OFFSETS 


TASK REQUEST BLOCK OFFSETS (MOD 400 ONLY) 
Macro Call Name: STRBD 


Generated Label Prefixes: 


T RRB/T_SEM 
TRB label offset 0 
TY CT 1 
TCT? 
T ADR 
T PRM 
See Appendix A for the format of the task request block. 


Description: 
see the task regquest block macro call. 
NOTE: This macro call cannot be used in programs written in 


SAF/LAF independent code (SLIC). See the Program 
Preparation manual for more information about SAF/LAF 


independent code. 


teat 
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TERMINATE REQUEST 


TERMINATE REQUEST 
Macro Call Name: STRMRQ 
Function Code: 01/04, 01/03 


Equivalent Command: None 


Terminate the current request being processed by the issuing 
task. End the current request for the execution of the task 
and mark its associated request block as terminated. 


FORMAT: 


[label] STRMRQ_ [location of completion status], 
[location of new task error address] 


ARGUMENT DESCRIPTION: 
location of completion status 


Any address form valid for a data register; provides 
the user-selected status code that is to be returned 
when the current request and its associated request 
block are terminated. Completion status codes 0801, 
0802, and 0803 should not be used; they will be 
indistinguishable from error codes with the same 
values. 


location of new task start address 


Any address form valid for an address register; pro- 
vides the new task start address for the terminating 
task. This address will subsequently be requested by 
a request block that does not explicitly specify a 
Start address. 


FUNCTION DESCRIPTION: 


This call is used to end a request for the execution of a 
task. The STRMRQ function marks a current request block as 


terminated and removes it from the appropriate request 
queue. 
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If there are no other request blocks on the request queue 
affected by the terminate function, the task manager places 
the task in a dormant state. If there are one or more 
request blocks in the affected queue, the task manager imme- 
diately uses the next request block to begin execution of 
the task at the indicated start address. If the task is 
requested for deletion and there is no other request for it 
the task is deleted; if this is a spawned task, it is 
deleted. 


The task manager will do one of the following: 


1. Activate a task if that task is awaiting completion of 
the current request block being terminated. 


2. Release (V-op) the semaphore indicated by the current 
request block. 


3. Schedule the task request block indicated by the current 
request block being terminated. 


If the terminating task will subsequently be requested by a 
request block that does not explicitly specify a task start 
address, the terminating task can specify the new task 
address through argument 2. 


NOTES: 1. The completion status code supplied through 
argument 1 is placed in $R2; if this argument is 
omitted, S$R2 is assumed to contain the comple- 
tion status code. 


2. If argument 2 contains the location of the new 
task start address, that address is placed in 
SB4 and an MCL 01/04 -is issued. If argument 2 
specifies =$B4, S$B4 is assumed to contain the 
new start address and an MCL 01/04 is issued. 
If argument 2 is omitted, $B4 is not modified 
and an MCL 01/03 is issued (no new task start 
address). 


3. On return, SB4, $B5, and SB7 contain the follow- 
ing information: 


SB4 - Address of request block for new request. 


SB5 - Address of system supplied termination 
routine. | 


SB7 - Address of the request block parameter 
list. 
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Example: 


In this example, the STRMRQ macro call labeled TRM_NM 
terminates the issuing task with a completion Status of zero 
without changing the task's start address. The STRMRQ macro 
call labeled TRM AB terminates the issuing task with a com- 
pletion status of one and changes the task's start address 
to RETRY. 


TRM NM STRMRQ- =O 


TRM_ AB STRMRQ =]1,!RETRY 
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TEST COMPLETION STATUS 


TEST COMPLETION STATUS 
Macro Call Name: STEST 
Function Code: 01/02 
Equivalent Command: None 


Return the completion status of any type of specified 
request block (e.g., task, clock, I/O, or semaphore). 


FORMAT: 

[label] “STEST [location of request block address] 
ARGUMENT DESCRIPTION: 
location of request block address 


Any address form valid for an address register; pro- 
vides the address of the request block whose comple- 
tion status is to be tested. 


FUNCTION DESCRIPTION: 


This call permits a running task to ascertain whether a 
specified request block has been marked as terminated by 
another task. When the call is executed, control is 
returned to the issuing task with SR1 containing a return 
Status that shows whether the request block has been 
terminated and $B4 containing the address of the tested 
request block. 


The test macro call does not cause a wait for the request 
block to be terminated; that function is performed by the 
wait macro call. 


A given request block can be tested by any number of tasks. 
NOTES: 1. The reguest block address supplied by argument l 
is placed in $B4; if this argument is omitted, 


_ SB4 is assumed to contain the address of the 
( request block to be tested. 
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2. On return, S$R1 and $B4 contain the following 
information: 


SR1 - Return status; one of the following: 


yyzz - Where yy can be 00, or O00 through 
EE for user status, or as defined 
for other yy values in the System 
Messages manual. 


SB4 - Address of tested request block. 
Example: 


In this example, the STEST macro call is used to determine 
the status of a task that was requested uSing a request 
block labeled TRB. If the requested task has not run to 
completion yet, a status of 0801 (hexadecimal) will be 
returned in SR1 and the t-bit in the request block will be 
on. If the requested task has run to completion, or has so 
indicated by posting the request block through a terminate 
request macro call, the posted completion status will be 
ota in S$Rl and the t-bit in the request block will be 
off. 


STEST !'TRB 
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TEST FILE 


TEST FILE 

Macro Call Names: STIFIL (input), STOFIL (output) 
Function Codes: 10/62 (STIFIL), 10/63 (S$TOFIL) 
Equivalent Command: None 


Test the status of any outstanding I/O activity. These 
macro calls are used in conjunction with I/O operations 
where the device to/from which the data transferred is a 
terminal. You identify the file by supplying its logical 
file number (LFN) in the file information block (FIB). 


FORMAT : 


[label] j STIFIL [,fib address] 
ae 


ARGUMENT DECRIPTION: 
fib address 


Any address form valid for an address register; pro- 
vides the location of FIB. The FIB must contain a 
valid LFN. 


FUNCTION DESCRIPTION: 


When a terminal file is opened (see "Open File"), a physical 
connect is issued asynchronously; a wait-until-complete 
(i.e., line physically connected) is not done. Issuing a 
test file macro call after the file is opened causes a busy 
code to be returned until the connect is complete. If the 
connect is not complete within 5-minute standard time, a 
physical I/O time-out code (0106) is returned by any file or 
data management function (e.g., STIFIL, SRDREC) issued by 
your program. Since the time-out code does not cause the 
file to be closed, any further access to the terminal (1.e., 
reopen to raise the connect again) must be preceded by a 
close file macro call. Once the connect is satisfied, the 
first test file macro call issued to an input or bidirec- 
tional LFN (after a successful connect) causes a read-ahead 
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(i.e., anticipatory read) to be issued. Furthermore, a read 
is requeued following a successful read record macro call. 


When the terminal file is closed, the sytem waits for the 
completion of any outStanding write orders, dequeues any. 
anticipatory reads, and issues a disconnect. 


The file information block can be generated by a SFIB macro 
call. Displacement tags for the FIB can be defined through 
the STFIB macro call. 


NOTES: 1. If the argument is coded, the address of the FIB 
is loaded into SB4; if the argument is omitted, 
SB4 is assumed to contain the address of the 
FIB. | 


2. On return, SR1 contains one of the following 
status codes: 


O000 - No error 

0204 - File busy 

0205 - Illegal argument 

0206 —- Unknown or illegal LFN 
0207 - LFN not open 


In addition to the above codes, any system 
service codes received by the file manager are 
passed on through SRl. 


Example: 


In this example, a terminal file, FILE T, associated with 
LFN 0006, has been reserved (see "Get File") and opened (see 
"Open File"). The following macro calls function as shown 
in the flowchart below. The FIB for FILE T is defined as: 


FILE T DC 2Z'0006! 


(Remainder is the FIB) 


5-368 | CBO8 


Neape 


$TIFIL FILE T 


INTERACTIVE NO 
DEVICE? 
YES 
NO 
YES 


ANTICIPATORY 
READ ISSUED 


YES READ NO 
COMPLETE 
RETURN RETURN 
(NOT BUSY) (BUSY) 


STOFIL FILE T 


NETURN 
(NOT BUSY} 


es: os 


RETURN 
(BUSY) 


WRITE IN 
_ PROGRESS 


RETURN RETURN 
(NOT BUSY) (BUSY) 
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TRAP HANDLER CONNECT 


TRAP HANDLER CONNECT 
Macro Call Name: $TRPHD 
Function Code: 0A/00 
Equivalent Command: None 


Connect a user-written generalized trap handling routine 
entry point to the issuing task. 


FORMAT: 


[label] STRPHD [location of trap handling routine address] 
ARGUMENT DESCRIPTION: 


location of trap handling routine address 


Any address form valid for an address register; pro- 
vides the address of the user-written trap handling 
routine. This address (entry point) is entered at 


each occurrence of a user trap that has been enabled 
for that task. 


FUNCTION DESCRIPTION: 


The connect trap function identifies a user-written routine 
that provides an alternative to the system default trap 
handler's response to user trap conditions. If user trap 
conditions are handled by the system default trap handler, 
the task in which the condition occurs is aborted. 


Since trap conditions are handled in a task context, each 
task must identify the trap handler and enable the partic- 
ular trap numbers to be serviced on behalf of the task (see 
enable user trap macro call). When an enabled user trap 
condition occurs, control is transferred to the user-written 
trap handling routine rather than the system default 


routine. See Section 7 for more information about trap 
handling. 
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cf ks, 


NOTES: 1. The address of the user-written trap handling 
routine supplied by argument 1 is placed in SB4; 
if this argument is omitted, $B4 is assumed to 
contain the correct address. 


2. On return, S$R1 contains one of the following 
Status codes: 


O000 - No error 
0341 - Invalid trap handling routine address 


3. This macro call is required in order to enable a 
software simulated trap in a task that the user 
interrupts with the break function, and for 
which a PI or UW break response is entered. 


Example: 


In this example, the connect trap handler (STRPHD) macro 
call connects the routine labeled TRAPS as the issuing 
task's trap handler. The enable uSer trap macro call 
(SENTRP) enables the program interrupt and unwind traps for 
the task. All program interrupt and unwind traps for the 
issuing task will be directed to the routine labeled TRAPS. 
The disable user trap macro call (SDSTRP) disables all user 
traps for the issuing task. 


The remaining code illustrates the basic techniques used to 
write a user trap handler; it is not meant to be typical. 


cS eager an CB08 


a 
a ar" 


| 


—n 
> 
= 


| 


+e eh + + + C' F H F 


+ % 


* 
* 
* 


GETLIN 


+ 


FINISH 


+ ee FF 


TRAPS 


NAME THE PROGRAM TRAPS 


EQU 1 
E QU 49 


NAME THE PERTINENT TSA FIELDS 
EQU SB3.4 

CONNECT "TRAPS" AS THE TRAP HANDLER. 
STRPHD !'TRAPS 

ENABLE PROGRAM INTERRUPT AND UNWIND. 


SENTRP =PI T 
SENTRP =UW T 


READ A NEW DIRECTIVE FROM USER INPUT. 


SUSIN ILINE, =80 


DISABLE ALL TRAPS. 


SDSTRP =—] 


STRMRQ =SR2 


TRAP HANDLER FOR THIS TASK: 
SEND PROGRAM INTERRUPT TO "GETLIN" 
SEND UNWIND TO "FINISH". 


CMN +SB 3 INCREMENT B3 BY POINTER SIZE 
STB $B4,TSA W SAVE B4 

LAB $B4,GETLIN 

CMV SR3,PI T 

BE >+SA 

LAB SB4,FINISH 

STB SB4,SB3 

LDB SB4,TSA W RESTORE B4 

RTT 7 
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USER IDENTIFICATION 


USER IDENTIFICATION 

Macro Call Name: SUSRID 
Function Code: 14/00 
Equivalent Command: None 


Returns the user identification of the calling task group to 
a 29-character receiving field, plus a terminating space. 


FORMAT: 

[label] SUSRID [location of user id field address] 
ARGUMENT DESCRIPTION: 
location of user id field address 


Any address form valid for an address register; pro- 
vides the address of a 29-character, aligned, non- 
varying field, followed by a blank, into which the 
system will place the user identification associated 
with the issuing task group. 


FUNCTION DESCRIPTION: 


This call returns the task group's user id to a field in the 
issuing task. The user identification will consist of 
person, perSon.account, or person.account.mode, depending on 
the login id used. See the Operator's Guide for further 
details. : 


NOTES: 1. The address of the receiving user id field, 
supplied by argument 1, is placed in SB4; if 
this argument is omitted, $B4 is assumed to con- 
tain the address of the receiving field for the 
user id. | 


2. On return, SR1 contains the following status 
code: 


O0O00 —- No error 
0817 - Memory access violation 
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Example: 


In the following example, a 15-word field is set up in the 
issuing task and the SUSRID macro call is issued to place 
the user identification of the task group in that field. 


IDQ1 SUSRID YUSIDFL 


USIDFL RESV 15,A'AA 
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USER INPUT 


USER INPUT 
Macro Call Name: SUSIN 
Function Code: 08/00 


Equivalent Command: None 


Read the next record from the current input file for the 
task group of the issuing task. 


FORMAT: 


[label] SUSIN [location of record area address], 


[location of record size], 
[byte offset of beginning of record area] 


ARGUMENT DESCRIPTION: 
location of record area address 


Any address form valid for an address register; pro- 
vides the address of a record area in the issuing task 
into which the next record read from the current user- 
in file will be placed. 


location of record size 


Any address form valid for a data register; provides 
the size (in bytes) of the input record area whose 
address is given in argument l. 
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byte offset of beginning of record area 


Any address form valid for a data register; provides 
the byte offset of the beginning of the record area 
(from the address provided in argument 1). If argu- 
ment 3 is L, the record area begins at the left byte 
of the address specified in argument 1. If argument 3 
is R, the record area begins at the right byte of this 
address. Any other value is taken to be the location 
of the byte offset of the beginning of the record area 
from the address specified in argument 1. If argument 
2 is omitted, the record area is assumed to begin at 
the left byte of the address specified in argument l. 


FUNCTION DESCRIPTION: 


This call allows a task to read the next record from the 
current user-in file. Unless it has been changed by a new 
user-in (SNUIN) macro call, the user-in file is that file 
identified in the request group (SRQOGRP) or enter batch 
request (SRQBAT) macro call. 


NOTES: ala 


The address of the record area supplied by 
argument 1 is placed in SB4; if this argument is 
omitted, $B4 is assumed to contain the record 
area address. 


The record size supplied by argument 2 is placed 
in S$R6; if argument 2 is omitted, SR6 is assumed 
to contain the record size. 


If argument 3 is L, SR7 is set to zero to desig- 
nate that the record area begins in the left | 
byte of the specified address. If argument 3 is 
R, SR7 is set to one to designate that the 
record area begins in the right byte of the 
specified address. Any other argument 3 value 
is assumed to designate the location of the byte 
offset from the address specified by argument l 
and is placed in SR7. If argument 3 is omitted, 
the record area is assumed to begin in the left 
byte of the specified address and SR7 is set to 
zero. 


On return, SR1, SR6, SR7, and $B4 contain the 
following information: 


SR1 - Return status; one of the following: 


QO0O00 - No error 
0817 - Memory access violation 
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( All data management read-next-record 
: error codes may also be returned in SRl. 
See the System Messages manual. 


SR6 - Residual range (number of bytes not filled 
in input record area) 


SR7 - File status/type (see "Command In") 


SB4 - Address of input record area 


Example: 


In this example, the issuing task is to read the next record 
of the current user-in file into a 64-byte record area 

whose address is in RECAD. The record area begins at the 
left byte of the indicated address. 


INAA SUSIN !RECAD, =128 


RECAD RESV 64,0 


pre 
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USER OUTPUT 


USER OUTPUT 
Macro Call Name: SUSOUT 
Function Code: 08/01 


Equivalent Command: None 


Write the next output record to the current user-out file 
for the task group of the issuing task. 


FORMAT: 


[label] SUSOUT [location of record area address], 


[location of record size], 
[byte offset of beginning of record area] 


ARGUMENT DESCRIPTION: 
location of record area address 


Any address form valid for an address register; pro- 
vides the address of the output record area containing 
the record to be written to the user-out file. The 
first byte of the record must be a slew byte (print 
file format control byte; see "Printer Driver" in 


Section 6). The record text begins in the second 
byte. 


location of record size 


Any address form valid for a data register; provides 
the size (in bytes) of the record area whose address 


is given in argument 1. The size value must include 
the slew byte. 
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byte offset of beginning of record area 


Any address form valid. for a data register; provides 
the byte offset of the beginning of the record area 
(from the address provided in argument 1). If argu- 
ment 3 is L, the record area begins in the left byte 
of the address specified in argument 1; if argument 3 
is R, the record area begins in the right byte of this 
address. Any other value is taken to be the location 
of the byte offset of the beginning of the record area 
from the address specified in argument 1. If argument 
3 is omitted, the record area is assumed to begin at 
the left byte of the address specified in argument 1 
and SR7 is set to 0. 


FUNCTION DESCRIPTION: 


This call allows a task to write the next record to the cur- 
rent user-out file. Unless it has been changed by a new 
user output (SNUOUT) macro call, the user-out file is as 
identified by the request group (SRQGRP) or enter batch 
request (SROBAT) macro call. 


NOTES: 


l. The address of the record to be written, Sup- 
plied by argument 1, is placed in $B4; if this 
argument is omitted, $B4 is assumed to contain 
the address of the’output record. 


2. The output record size, supplied by argument 2, 
is placed in SR6; if this argument is omitted, 
SR6 is assumed to contain the size of the output 
record. 


3. If argument 3 is L, $R7 is set to zero to desig- 
nate that the record area begins in the left 
byte of the specified address. If argument 3 is 
R, SR7 is set to one to designate that the 
record area begins in the right byte of the 
specified address. Any other value is assumed 
to be the location of the byte offset to be 
used, and is placed in S$R7. If argument 3 is 
omitted, the record area iS assumed to begin in 
the left byte of the specified address and SR7 
is set to zero. 


4. On return, SR1, S$R6, and SB4 contain the follow- 
ing information: 


SR1 - Return status; one of the following: 


0000 -—- No error 
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All data management write-next-record 
error codes may also be returned. See the 
System Messages manual. 


SR6 - Residual range (number of bytes not 
transferred from record area). 


SB4 - Address of record area containing output 
record. 


Example: 
In this example, the issuing task is to write the next | 
record to the current uSer-out file for its task group. The 


record length is 137 bytes (including the slew byte). The 


output record begins at the right byte of the word labeled 
REC AR. 


SUSOUT !REC AR, +=137,R 


REC_AR TEXT 'AA', (136) 'A' 
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WAIT 


Macro Call Name: SWAIT 
Function Code: 01/00 


Equivalent Command: None 


Wait for the completion of the operation that uses the 
Specified request block (task, I/O, semaphore, clock, or 
overlay). 


FORMAT: 

[label] SWAIT [location of request block address] 
ARGUMENT DESCRIPTION: 
location of request block address 


Any address form valid for an address register; pro- 
vides the address of the request block whose termina- 
tion is to be awaited by the issuing task. 


FUNCTION DESCRIPTION: 


This call permits a running task to indicate, as a separate 
action, that it wishes to wait for the completion of a 
particular request for the execution of another task. (The 
capability of the synchronous wait function is available 
through the request task function.) 


When a wait macro call is issued, the issuing task must Sup- 
ply the address of the request block to be waited upon. If 
the task manager discovers that this request block is marked 
as terminated, it immediately returns control to the calling 
task, supplying the completion status code of the terminated 
request. If the request block is not marked as terminated, 
the task manager stores the identity of the calling (and now 
waiting) task in the request block and then suspends the 
calling task - another task can run at this task's level. 
Later, when the task manager is notified of the completion 
of the request being waited upon, it activates the waiting 
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task and reports the completion status code of the termi- 
nated request. 


A given request block can be waited upon by only one task. 


NOTES: 1. The request block address derived from argument 
1 is placed in $B4; if this argument is omitted, 
SB4 is assumed to contain the address of the 
request block. 


2. On return, SR1 and $B4 contain the following 
information: 


SR1 - Return status; one of the following: 


yyzz - Where yy can be 00 or 80 through EE 
for user status, or as defined for 
other yy values in the System 


Messages manual. 
OOOC-FFFF - Posted completion status 


0802 -—- Invalid LRN 


0803 - Illegal wait (request block already 
waited on, waiting on self, or 
request block not pending for this 
task). 


SB4 - Address of request block being waited upon 
Example: 


In this example the SWAIT macro call is used to block the 
issuing task until a task that was requested using the 
request block labeled TRB posts its completion to that 
request block. See "Terminate Request" for information 
about task termination. When the issuing task is returned 
to the ready state, the task's posted completion status will 
be in SRl. 


WAIT 1 SWAIT  !TRB 
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( ~ WAIT BLOCK 


WAIT BLOCK 
Macro Call Name: SWTBLK 
Function Code: 12/20 


Equivalent Command: None 


Wait for the completion of the I/O operation associated with 
the specified buffer. This macro call is used only when the 
asynchronous bit is set in the program view entry in the 


file information block (FIB) for the preceding read block or 
write block macro call. 


FORMAT: 


r [label] SWTBLK [fib address] 
ARGUMENT DESCRIPTION: 


fib address 


Any address form valid for an address register; pro- 
vides the location of the FIB. The following FIB 
entries are required. 


logical file number 

program view (must specify asynchronous I/O) 
user buffer pointer 

transfer size 

block size 

block number 


FUNCTION DESCRIPTION: 


This macro call immediately follows a read block or write 
block macro call. The buffer identified by the user buffer 
pointer entry in the FIB must not be accessed between the 
read block or write block macro call and the wait block 
macro call, as shown below: 
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SRDBLK (block 0) — 
SWTBLK (block 0) Sunk 
SRDBLK (block 1) i | 
(process block 0) 
SWTBLK (block 1) 

SRDBLK (block 2) 

(process block 1) 


Furthermore, only one asynchronous operation per file can be 
outstanding at any given time. 


The file information block (FIB) can be generated by a SFIB 
macro call. Displacement tags for the FIB can be defined by 
the STFIB macro call. | 


NOTES: 1. If the argument is coded, the address of the FIB 
is loaded into $B4; if the argument is omitted, 
SB4 is assumed to contain the address of the 
FIB. 


2. On return, SR1 contains one of the following 
status codes: 


OQO00 - No error 

0203 - Illegal function 

0205 - Illegal argument 

0206 - Unknown or illegal LFN 
0207 - LFN not open | 
O20A - Address out of file 
0217 - Access violation 

O21F - End of file 


In addition to the above codes, any system 
service codes received by the storage manager 
are passed on through SRl. 


Example: 


In this example, it is assumed that the read block macro 
call was coded as described above, except that the program 
view entry specified Z'EO0O1'. Based on this assumption, the 
wait block macro call would be coded as follows: 


WAITAA SW TB LK !'BLKF IB 
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WAIT FILE 


WAIT FILE 

Macro Call Name: SWIFIL (input), SWOFIL (output) 
Function Codes: 10/64 (SWIFIL), 10/65 (SWOFIL) 
Equivalent Command: None 


Wait for the completion of an asynchronous I/O activity. 
SWIFIL and SWOFIL are used in conjunction with I/0 opera- 
tions in which the device to/from which data is transferred 
is a terminal. You specify a list of logical file numbers 
(LFNS) identifying the files to be checked by the wait func-— 
tion. If the SWIFIL macro call is used, the function waits 
until at least one anticipatory read to one of the specified 
Files is complete. If the SWOFIL call is used, the function 
waits until at least one write to one of the specified files 
is complete. The first LFN for which an anticipatory read 
(SWIFIL) or an asynchronous write (SWOFIL) is complete is 
placed in a field that you specify. 


FORMAT: 


SWIFIL 


[label] ioe 


\ [parameter structure address] 


ARGUMENT DESCRIPTION: 
parameter Structure address 


Any address form valid for an address register; pro- 
vides the location of the argument structure defined 
below. The argument structure must contain the fol- 
lowing entries in the order shown. 


out-LFN 
A 2-byte field into which file management places 


the LFN (logical file number) that was the first 
LFN in the list for which I/O was complete. 
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list length 


A 2-byte field containing a binary number that 
specifies the number of LFNs in the list. If 
this field is zero (meaning no list of LFNs is 
specified), file management assumes a list of 
LFNS consisting of all LFNs in the task group 
that are currently associated with opened, 
interactive devices. 


LFN entries 


A series of 2-byte fields, each containing the 
2-byte logical file number (LFN) used to refer 
to the file. LFN is a binary number in the 
range 0 through 255. Each referenced file must 
have been reserved (see "Get File") and opened 
(see "Open File") through this LFN. The LFNs in 
the list are considered to be in order of prior- 
ity; the first LFN specified for which I/O has 
completed will be returned in the out-LFN field. 


FUNCTION DESCRIPTION: 


A wait-file-input function (SWIFIL) is meaningful only for 
interactive device files that allow asynchronous input; this 
function gives up control of the central processor until at 
least one anticipatory read to any of the specified files is 
complete. A wait-file-output function (SWOFIL) is meaning- 
ful only for interactive device files that allow asynchro- 
nous output; this function gives up control of the central 


processor until output to one of the specified files is 
complete. 


When a wait-file-input function is executed, the out-LFN 
field is set to identify the first LFN in the list for which 
an anticipatory read is complete. Since more than one read 
may be completed at the same time, a STIFIL (see "Test 
File") macro call can be used after the SWIFIL call to 
ascertain those LFNs for which input is complete. Note that 
the first SWIFIL call issued after the file has been opened 
waits for the connect termination (initiated at the time of 


the open) in addition to waiting for the completion of the 
first read. 


When a wait-file-output function is executed, the out-LFN 
field is set to identify the first LFN in the list for which 
an aSynchronous write operation is complete. This function 
returns the status of the write operation. If the write 


terminated normally, the file can be considered as available 
for output. 


97-386 CBO08 


The LFNs in the list are considered to be ordered by prior- 
ity; thus the first LFN for which I/O has completed will be 
returned in the out-LFN field. You can ignore the output 
LFN and establish your own priority by using the test-file- 
input and test-file-output functions (see "Test File"). For 
example you could: 


- Issue a SWIFIL for LFNs 1, 2, and 3. 

- IkIssue a STIFIL for LFN 2; read and process if not busy. 
- Do the same for LFN 1 and LFN 3. 

- Return to l. 


Mm WH 


NOTES: 1. If the argument is coded, the address of the 
argument structure is loaded into $B4; if the 
argument is omitted, SB4 is assumed to contain 
the address of the argument structure. 


2. On return, SR1 contains one of the following 
status codes. 


0205 Illegal argument (duplicate LFN) 
0206 -— Unknown or illegal LFN 

0207 LFN not open 

0217 - Access violation 


In addition to the above codes, any system 
Service codes received by file manager are 
passed on through SRl. 


Example: 


In this example, a wait-file-input function is executed to 
wait for the completion of a write operation on any of three 
interactive files whose LFNs are 1, 2, and 3. The comple- 
tion of a write operation on the file associated with LFN 3 
is checked first; if the write is complete, LFN 3 is placed 
in the out-LFN field. If the write is not complete, LFN 1'S 
file is checked; if not complete, the file associated with 
LFN 2 is checked. If none of the write operations are 
completed, the task is placed in the wait state. 


IWTLST DC 


DC 


0 
3 
DC 3 
L 
2 
ONW TBB SWIFIL i 


IWTLST 
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WAIT LIST, GENERATE 


WAIT LIST, GENERATE 

Macro Call Name: SWLIST 
Function Code: None 
Equivalent Command: None 


Generate a wait list consisting of a count field followed by 
the specified number of request block pointers. A maximum 
of 35 request block pointers can be specified. 


FORMAT: 


[label] SWLIST [request block label 1], 
[request block label 2], 


[request block label 35] 
ARGUMENT DESCRIPTION: 
request block label 1 ... request block label 35 


Label of the request block to be placed in the wait 
list. A maximum of 35 blocks can be specified. 


If a label having a value of 0 is specified before the 
last label is supplied, an address of 0 is generated 
for the wait list entry that corresponds to that argu- 
ment position. See Appendix A for the format of the 
wait list. 


FUNCTION DESCRIPTION: 
A wait list consists of a count of the number of request 


blocks to be waited on, followed by the specified number of 
request block pointers. 


When any request block referenced in the wait list provided 
in a wait on request list macro call has been posted as 
complete, the issuing task is awakened. | 
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A wait list can refer to any mixture of request blocks. 


If any pointer in the wait list is zero, it is ignored by 
the wait on request list macro call. 


The count field format is Olnn (where nn is the number of 
request block pointers specified in the macro call). 


NOTE: This macro call cannot be used in programs written in 


SAF/LAF independent code (SLIC). See the Program 


Preparation manual for more information about SAF/LAF 
independent code. 


Example: 


In this example, a SWLIST macro call is used to generate a 


list of three request block addresses (following the count 
field of 0103). 


ALSTA SWLIST TSKBO1, TSKB02, TSKBO3 
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WAIT ON REQUEST LIST 


WAIT ON REQUEST LIST 
Macro Call Name: $WAITL 
Function Code: 01/01 
Equivalent Command: None 


Check the completion status of request blocks. The request 
blocks specified in the list can be a mixture of types 
(task, clock, I/O, semaphore, or overlay). 


FORMAT: 


[label] SWAITL [request block label 1], 
[request block label 2], 


[request block label 35] 
ARGUMENT DESCRIPTION: 
request block label 1 ... request block label 35 


Label of the request block to be placed in the wait 
list. A maximum of 35 blocks can be specified. 


If a label having a value of 0 is specified before the 
last label is supplied, an address of 0 iS generated 
for the wait list entry that corresponds to that argu- 
ment poSition. See Appendix A for the format of the 
wait list. 


FUNCTION DESCRIPTION: 


This call permits a running task to indicate that it wishes 
to wait for any one of up to 255 request blocks (of any 
type) to be marked as terminated. (Note that only 35 
request blocks can be specified directly in the macro call.) 
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The task manager scans the wait list and checks the status 
of the specified request blocks. If it finds any request 
block marked as terminated, the task manager returns imme- 
diately to the calling task. If it finds that no request 
block in the list is marked as terminated, the task manager 
suspends the calling task until at least one of the blocks 
is marked as terminated. When the task manager is notified 
of the termination of a request block specified in the list, 
it activates the waiting task and reports the completion 
code of the terminated request. 


NOTES: 1. If arguments are specified, a wait list is 
generated. The address of the wait list sup- 
plied by argument 1 is placed in $B2; if the 
arguments are omitted, $B2 is assumed to contain 
the address of the wait list. 


2. Upon return to the issuing task, S$Rl, $B2, and 
SB4 contain the following information: 


SR1 - Return status; one of the following: 


yyzz - Where yy can be 00 or 00 through EE 
for user status, or as defined for 
other yy values in the System 
Messages manual. 


OCOO-FFFF - Posted completion status of 
first completed request block 
detection. 


0202 -—- Invalid LRN. 


0803 - Illegal wait; (request block 
already waited on; or not pending 
for this task; or all pointers on 
this wait list were null). 


SB2 - Address of wait list 


SB4 - Address of request block that caused 
return (i.e., first completed request 
block found); if null, all pointers in the 
wait list were null. 


3. If arguments are present, this macro call cannot 
be used in programs written in SAF/LAF indepen- 
dent code (SLIC). See the Program Preparation 
manual for more information about SAF/LAF 
independent code. 
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Example: 


In this example, the request clock macro call (SROQCL) is 
issued to start a 5-second timer using the clock request 
block labeled TIMER. Then the wait on request list macro 
call (SWAITL) is used to block the issuing task until either 
the task that was requested using a request block labeled 
TRB posts its completion or the clock manager posts comple- 
tion of the 5-second interval on the clock request block 
labeled TIMER. If the task goes to completion first, the 
cancel clock request macro call (SCNCRQ) will cancel the 
request on TIMER, thus freeing it for later reuse. To 
Simplify the Scenple: the return status will not be checked 
for errors that might occur. 


SROCL !ITIMER 
SWAITL TRB, TIMER 
CMB SB4,=TIMER 
BE T OUT 


+ 


THE SUBTASK COMPLETED FIRST 


SCNC RQ ! TIMER 


* 

* THE CLOCK TIMED OUT FIRST 

* 

T OUT EQU S 

TIMER SCRB R, NWAIT, ,MS=5000 
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WRITE BLOCK 


WRITE BLOCK 

Macro Call Name: SWRBLK 

Function Code: 12/10 (normal), 12/11 (tape mark) 
Equivalent Command: None 


Write (i.e., transfer) a block from a buffer in main memory 
to a file. The user must supply a buffer and specify both 
the size of the block and its relative location in the file. 
FORMAT: 


oan 
,TM 


[label] SWRBLK [fib address] |{ 
ARGUMENT DESCRIPTION: 
fib address 
Any address form valid for an address register; pro- 
vides the location of the file information block 
(FIB). The following FIB entries are required. 
logical file number 
program view (Should include buffer alignment and a 
whether the next write operation is synchronous or 
asynchronous) 
user buffer pointer 


transfer size 


block size (must be a multiple of the physical sector 
size) 


block number 
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NORMAL 
NOR 


For disk-resident files this mode argument indicates 
that the contents of the buffer are to be written in a 
control interval whose block number is specified in 
the block number entry in the FIB. | 


For nondisk-resident files this mode argument indi- 
cates that the block is to be transferred from the 
buffer to the next sequential position on the file. 


NORMAL is the default value for this macro call. 
TM 


(For tape-resident files only.) This mode argument 
indicates that a tape mark is to be written in the 
next sequential position on the tape. 


FUNCTION DESCRIPTION: 


Before this macro call can be executed, the LFN must have 
been opened (see open file macro call) with a FIB program 
view word that allows access via Storage management (bit 0 
is 1) and allows write operations (bit 2 is 1). To write a 
file sequentially, it is necessary only to issue successive 
write block macro calls in NORMAL mode, which causes the 
block number entry to be incremented by 1 after each 
transfer. The system extends the file space up to the limit 
specified in the create file macro call when required to do 
So aS a result of a write block macro call. In addition, 
the system updates the logical end-of-file as the file is 
extended. 


The following end-of-file/end-of-tape considerations must be 
noted: 


Oo Tape-resident files. If logical end-of-tape (i.e., EOT 
reflector) is detected during a write block macro call, 
all data is written and status code 0231 is returned. If 
physical end-of-tape is reached before all data is 
written, a code of 0231 is also returned. | 


o Disk-resident files. If there is insufficient space to 
contain the data defined by the transfer Size entry in 
the FIB (i.e., the file has reached itS maximum size), a 
Status code of 0223 is returned. If the file has not 
reached itsS maximum size but no more sectors are avail- 
able to be allocated to it, a code of 0215 is returned. 
No data is written. 


o All files. Partial blocks are not written. 
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( Only one asynchronous I/O operation per LFN can be out- 
Standing at any given time. 


The file information block (FIB) can be generated by a SFIB 
macro call. Displacement tags for the FIB can be defined by 
the STFIB macro call. 

NOTES: 1. If the first argument is coded; the address of 
the FIB is loaded into $B4; if the argument is 
omitted, $B4 is assumed to contain the address 
of the FIB. 


2. On return, S$R1 contains one of the following 
status codes: 


OO00 - No error 
0203 - Illegal function 
0205 - Illegal argument 
0206 - Unknown or illegal LFN 
0207 - LFN not open 
a O20A - Address out of file 


0215 - Not enough contiguous logical sectors 
available 


0217 - Access violation 


0223 - File space limit reached or File not 
Be ae 


0224 - Directory space limit reached or not 
expandable 


0231 - Unexpected tape EOT encountered 
In addition to the above codes, any system 


service codes received by the storage manager 
are passed on through SRI. 
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Example: 


This example assumes that the FIB was defined as follows: 


BLKFIB DC Z* 0005" LFN = 5 
DC Z'EOOO' PROGRAM VIEW = ALLOW READ/WRITE; 
SYNCHRONOUS PROCESSING 
DC <BLKBUF BUFFER POINTER 
RES V 2-SAF 
DC 256 TRANSFER SIZE = 256 
DC 256 BLOCK SIZE = 256 
DC Z'OOO0O0O000! BLOCK NUMBER 


When the above FIB is defined, and assuming the appropriate 
open file and get file macro calls are specified, the fol- 
lowing macro call can be executed to write the contents of 
the buffer into the first block (i.e., block (©) in the file: 


SWRBLK !1BLKFIB, NORMAL 
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WRITE RECORD 


WRITE RECORD 


Macro Call Name: SWRREC 


Funtion Code: 11/20 (next), 11/21 (key), 11/22 (position equal), 
11/23 (position greater than), 11/24 (position 
greater than or equal), 11/25 (position forward), 
11/26 (position backward) 


Equivalent Command: None 


Transfers logical records to a file from your record area or 
merely positions the write pointer to a desired record. 
Whether to transfer or position is specified by the second 
(i1.@€., mode) parameter. 


FORMAT: 


, NEXT 

, KEY 

, POSEQ 
[label] SWRREC [fib address] , POSGR 

, POSGREQ 

, POSEFWD 

, POSBWD 


ARGUMENT DESCRIPTION: 
fib address 
Any address form valid for an address register; pro- 


vides the location of the file information block 
(FIB). 
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NEXT 
NXT 


KEY 


| 


(For all files.) This mode argument indicates that 
the record is to be written into the position in the 
file identified by the write pointer. The write 
pointer is set to the next logical record in the file 
after the write is complete. The system ensures that 
the position pointed to is unused or contains a 
deleted record. Records are written in the file as 
described in the Data File Organizations and Formats 
manual. This is the default for this macro call. You 
must code the following FIB entries: 


logical file number 

program view (record area alignment) 
user record pointer 

output record length 


After the record is transferred to the file, the 
system updates the following FIB entry: 


output record address (serial sequence number if 
device file; BSN if tape file; simple key unless 
relative access specified at open time). 


This mode is referred to as write next. 


(For disk files accessed by key, only.) This mode 
argument indicates that the record is to be written 
into a position in the file, based upon the key value. 
The write pointer is set to the next logical record in 
the file after the write is complete. Records are 
written as described in the Data File Organizations 
and Formats manual. You must code the following FIB 
entries: 


logical file number 

program view (record and key area alignment) 
user record pointer 

output record length 

input key pointer 

input key format 

input key length 
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| PosEQ 


) PEO 


After the record is transferred to the file, the 


system updates the following FIB entry: 
output record address 


This mode is referred to as write with key. 


(For disk files accessed by key, only.) This mode 
argument positions the write pointer to the first 
position in the file whose key value is equal to the 
one specified in the FIB. It is normally followed .by 
write next macro calls to load the file starting from 
that position. You must code the following FIB 
entries: 


logical file number 
program view 

input key pointer 
input key format 
input key length 


This mode is referred to as read position equal. 


(For disk files accessed by key, only.) This mode 
argument positions the write pointer to the first 
position in the file whose key value iS greater than 
the one specified in the FIB. It is normally followed 
by write next macro calls to load the file starting 
from that position. The same FIB entries as for POSEQ 
above must be coded. This mode is referred to as 
write position greater than. 


POSGREOQ 
PGE 


(For disk files accessed by key only.) This mode 
argument positions the write pointer to the first 
position in the file whose key value is greater than 
or equal to the one specified in the FIB. It is 
normally followed by write next macro calls to load 
the file starting from that position. The same FIB 
entries as for POSEQ above must be coded. This mode 
is referred to as write position greater than or 
equal. 
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PED ( : 
(For tape-resident and relative files only.) This 
mode argument moves the write pointer forward the 
number of record positions specified by the key value 
identified in the FIB (but not beyond the end of 
file). The same FIB entries as for POSEQ above must 
be coded. This mode is referred to as write position 
forward. : | 

posawol 

PBD 


(For tape-resident and relative files only.) This 
mode argument is the same as for POSFWD above except 
that the pointer is moved backward the number of 
record positions specified by the key value in the 
FIB (but not before the first record). This mode is 
referred to as write position backward. 


FUNCTION DESCRIPTION: 


Before thiS macro call can be executed, the LFN must have 
been opened (see the open file macro call) with a program 
view word that allows access via data management (bit 0 is 
0) and allows write operations (bit 2 is 1). The file must 
be reserved (see the get file macro call) with write access 
concurrency control (type 3, 4, or 5). The write pointer is 
a logical pointer to where the next record is to be written; 
it is maintained separately from the read pointer. There is 
one write pointer per LFN per user. At open file time, the 
write pointer is set to the first record (if RENEW 
Specified) or logical end-of-file (if PRESERVE specified). 
The write pointer is modified by each write record 
operation. 


3 


The file information block can be generated by a $FIB macro 
call. Displacement tags for the FIB can be defined by the 
STFIB macro call. 


The following illustrates the effect of write actions 
according to file organizations. 
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File Organization 


Sequential 


Relative 


Indexed 


Effects of Write Action 


Write next: If the file is being created 
(i.e., opened in RENEW mode), the records 
start at the beginning of the file. If the 
file is not being created, the records are 
appended to the end of the existing file. 


The position modes POSEQ, POSGR, or POSGREOQ 
may be specified to do a "partial file 
renewal" or a "file shrink." These modes 
use a simple key to address (set write 
concurrency) an active record. The result- 
ing new end-of-data must lie within the file 
limits that existed before the write 
operation. 


Write next, issued immediately after an 

open file, appends a record to the end of 

an existing file. In RENEW mode, this 
action can be used to create the file 
Sequentially. Write next issued after a 
write next, write with key or with any 
position mode, inserts a record in the 

next available (unused or deleted) space. 

A write next searches for the next available 
spaces in which to place the record. 


Write with key uses a relative or simple 
key that must address a deleted record or 
an unused space. 


All position modes uSe a relative or 
Simple key to address (set write currency 
to) an active record, deleted record, or 
unused space. 


Write next and write with key (uSing a key 
format that indicates a primary key) pro- 
duce identical results. A write with key 
operation verifies that the key lengths 
and key format information in the FIB are 
correct and that the key pointer refers to 
the proper position in the user record 
area. The write next operation does not 
perform these checks. 
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File Organization 


Indexed (cont) 


Fixed Relative 


Device Files 


Effects of Write Action 


If the file is being initially loaded, it 
Should be opened in RENEW mode, with the 
data to be written sequenced in ascending 
order by primary key. Data management 
will verify that the supplied keys are in 
order, and will generate a key out of 
sequence error if they are not. When 
inserts are to be made, the existing file 
should be opened in PRESERVE mode. 


Fixed relative with nondeletable records: 
Write next, issued immediately after an 
open file, appends a record to the end of 
an existing file. In RENEW mode, this 
action can be used to create the file 
sequentially. When issued after a write 
next, write with key, or any poSition 
mode, it inserts a record in the next 
logical record position. 


Write with key inserts a record in the 
Space addressed by the relative key. All 
position modes set write concurrency to 
the specified record. 


Fixed relative with deletable records: 
Write next, issued immediately after an 
open file, appends a record to the end of 
an existing file. In RENEW mode, this 
action can be used to create the file 
sequentially. Issued after a write next, 
Write with key, or any position mode, 
write next inserts a new record in the 
next available. (unuSed or deleted) space. 
This write next operation searches for the 
next available space in which to place the 
record. 


Write with key uses a relative key that 
must address a deleted record or an unused 
Space. 


All position modes use a relative key that 
addresses (sets write concurrency to) an 
active record, deleted record, or an 
unused record. 


Write next allows sequential writing, pro- 
vided the device can be written to and has 
been so defined. 
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If the first argument is coded, the address of 
the FIB is loaded into $B4; if this argument is 
omitted, SB4 is assumed to contain the address 
of the FIB. 


On return, SR1 contains one of the following 
status codes: 


0000 


0203 


0205 


0206 


0207 


O20A 


0217 


Q219 


O21A 


O21B 


O21C 


O21E 


0223 


0224 


0227 


O22A 


O22B 


No error 

Tllegal function 

Illegal argument 

Unknown or illegal LFN 
LFN not open 

Address out of file 
Access violation 

No current record pointer 
Record length error 
Duplicate key 

Key out of sequence 

Key length or location error 


File space limit reached or file not 
expandable 


Directory space limit reached or not 
expandable 


Index limit exceeded while loading an 
indexed file 


-Record lock area overflow 


Requested record is locked 


In addition to the above codes, any system 
service codes received by the data manager are 
passed on through SRl. 
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Example: 


In this example, the FIB (i.e., MYFIB) described under 
"Assumptions for File System Examples" in Section 3 is 
identified by the first argument. Assuming that the file 
has been reserved with write-access concurrency control, and 
that it has been opened as defined in the open file example, 
the macro call is specified as follows: 


SWRREC IMYFIB,NEXT 
After the record is written in the file, the system updates 
the following entry, which you can interrogate with the FIB 


offset tag: 


F_ORA (output record address) 
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SECTION 6 


INPUT/OUTPUT DEVICE DRIVERS 


This section describes the internal system software, known 
as device drivers, that provide data transfer facilities for 
system and application programs with peripheral devices. Macro 
calls pertaining to standard system file input/output and to 
physical input/output are summarized in Section 2 and described 
in detail in Section 5. | 


INPUT/OUTPUT DRIVERS 


Input/output peripheral drivers and the analogous communica- 
tions device drivers (called line protocol handlers) perform all 
data transfers between a peripheral device and the system or 
application program that uses it. Drivers are provided for all 
Honeywell-supplied peripheral devices and the teleprinter, VIP, 
and BSC2780/3780 protocols. 


The remainder of the section describes the peripheral device 
drivers. Line protocol handlers are described in the 
Communications Processing manual. 


Applications programs can call the drivers directly or can 
use them indirectly by calling the file manager. If you want to 
write a peripheral driver for a nonstandard device, or modify the 
Function of an existing peripheral driver, refer to Appendix B. 


You select a driver and the priority level at which it exe- 
cutes at system building. 


The input/output drivers are reentrant programs capable of 
supporting the concurrent operation of several devices of the 
Same type. The driver runs at the priority level assigned to the 
particular device at system building. The drivers provide fully 
simultaneous operation of the central processor with multiple 
input/output operations. Device interrupts Signal the termina- 
tion of data transfers. 


6-1 CBO8 


DEVICE DRIVER CONVENTIONS 


The following conventions apply to all input/output device 
drivers. 


o The I/O request block (IORB) is the standard control 
Structure used by a driver (see "Data Structures," later 
in this section for definition). 


o The SRQIO macro call iS used to request a driver. 


o The B4-register contains the address of the IORB supplied 
by the caller; the IORB contains the LRN of the device to 
be used. 


o The I/0-specific words of the IORB (I _CT2 through I DVS) 
are not modified by the driver. 


o If a device becomes inoperable, it can be disabled with 
an operator command and another device can be 
Substituted. : 


o Drivers are reentrant and interrupt driven; one driver 
Supports many devices of the same type. 


o Synchronous and asynchronous I/O are Supported. 


o Work space, if required, is located in the device's re- 
lated resource control table (RCT). 


o The hardware status is always mapped into the software 
Status word in the task's IORB (I _ ST) before the driver 
relinquishes control. 


Driver Functions and Function Codes 


All drivers perform similar functions on behalf of the de- 
vices and application tasks they service. These functions are 
carried out by the driver's request processing and interrupt 
processing code. 


The application task can request specific functions by pro- 
viding a function code in the IORB it supplies when it requests 
I/O service. These specific function codes are summarized in 
Table 6-1 and discussed under the specific function heading in 
the following pages. 
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The application task uses the last four bits of the IORB 
entry I CT2 to enter the function code for the functions sum- 
marized in Table 6-l. 


Table 6-1. Input/Output Function Code 


Device 


IORB ASR/KSR 
Function Keyboard/ Card Reader/ 
Code Printer Card Reader Punch Printer Magnetic Tape 


Wait online Wait online} Wait online Wait online | Wait online Wait online 
Write Write (punch) Write Write Write 
Read NA NA Read Read 


NA Write file mark | NA Write deleted data Write file mark 
(punch) 


NA NA Read deleted data Position block? 
NA NA Format write NA 
NA NA Format read Position file‘ 


Break Notification NA NA NA 
(KSR only) 


Connect Connect Connect Connect Connect Connect 


Disconnect Disconnect Disconnect Disconnect Disconnect Disconnect 


NA NA NA NA Read disabled device | Read disabled device 
"Not applicable. . 


‘Positive range of one is forward space to start of next block. 
Negative range of one is backspace to beginning of previous block. 


“Positive range of one is forward space to next tape mark. 
Zero range is backspace to previous tape mark. 

Negative range of FFFF is rewind to BOT. 

Negative range of FFFF is rewind to BOT and unload. 
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WAIT ONLINE FUNCTION (fc=0) 


The "wait online" function, one element of a control mecha- 
nism used to synchronize task operation with device availability, 
allows a caller to wait until a device becomes ready for use, or 
until a specific time interval has passed. 


All noncommunications devices (except KSR-like devices) gen- 
erate interrupts when their availability changes. For example, 
when a printer runs out of paper, an interrupt is generated and 
the device is not ready for use; when the paper is installed and 
the device is again ready, another interrupt is generated. 


When a driver receives a service request from a task uSing 
the “wait online" function code in the IORB that it supplies 
(0000 in the last four bits of I CT2), and the device is not 
ready, the driver sets a timer for 5 minutes and suspends. When 
the driver is reactivated, either by a ready interrupt from the 
device or by a time-out, it deactivates the timer, checks the de- 
vice-ready bit in the hardware status word and places a0 or 6 
value in the return status field of the IORB depending on the 
condition of that bit. See the return status codes for the SRQIO 
(Request I/O) macro call; the rightmost hexadecimal character is 
placed in the return status field. 


The wait online function should not be issued to a device 
that is currently ready for use unless you expect it to become 
not ready before it becomes ready again (e.g., the operator has 
been instructed to change a volume mounted on a disk device cur- 
rently in use). When the ready state of a device changes, the 
attention bit set in the RCT (R FLGS, bit 8) may be reset by a 
reset device attention (SRDVAT) macro call. 


A task can ask to be notified about the occurrence of an 
interrupt by a device by setting bit 9 of R_FLGS of the RCT (See 
the disable device (SDSDV) macro call.) When such an interrupt 
occurs, the driver will set bit 10 of R FLGS, and place the value 
8 in I ST of subsequent IORB's supplied by the requesting task. 
Subsequently, when a ready interrupt for the device is generated, 
the using task can clear the disabled status by resetting bit 10 
of R_FLGS (see SENDV (enable device) macro call). 


WRITE FUNCTION (fc=1) 


The write function is available for use by all devices ex- 
cept the card reader. This function allows the writing of data 
to a particular device. When a driver receives a write request, 
it transfers the indicated data from a user buffer to the device 
according to the specifications supplied in the task's IORB. 


6-4 CB08 


Table 6-2. Return Status Codes 


‘Code Number 

(Hexadecimal) Meaning 
Raa ae pee ET EE EITC LEAS SND aD DL AGU MG SIE ON IE PETC NT TOL SE EE AEE EOD 
No error, operation complete 

Request block already busy (T=1) 
Invalid LRN 

Illegal wait 

Invalid parameters 

Device not ready 

Device time-out 

Hardware error, check IORB status word 
Device disabled? 

File mark encountered 

Controller unavailable 

Device unavailable’ 

Inconsistent request 


0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 


“When these codes are found in I CTl (ITORB), or in 
SRl on a resume after wait, look at I ST (IORB) to 
identify the specific error. The status B is re- 
returned with every read or write IORB that has been 
aborted by a disconnect request with queue abort. 


“This status will be returned on an I/O request if 
the user program has disabled the logical resource. 
This event is indicated in the device resource 
control table (See Figure 6-2) by bit 10 of R_FLGS. 


“This status indicates illogical peripheral driver 
requests: read or write before connect; duplicate 
connect or disconnect requests; write after 
disconnect. 


READ FUNCTION (fc=2) 


The read function is available for use by all devices for 
local and remote printers. This function allows reading data 
from a particular device. When a driver receives a read request, 
it transfers the data from the specified device to a user buffer 
according to the specifications supplied in the requesting task's 
IORB. | 


READ DISABLED DEVICE FUNCTION (fc=E) 
This function, available only to disk or magnetic tape de- 


vices, allows the driver to bypass the device-disabled test dur- 
ing validity checking. 
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This function is used by the system's automatic volume rec- 


ognition (AVR) module, which recognizes the volume label of the 
volume on the disabled device, then enables the device so that 
attempts ro read data from it can continue. 


WRITE TAPE MARK FUNCTION (fc=3) 


The write tape mark function, which is available to magnetic 
tape devices, allows you to put a mark block on a referenced mag- 
netic tape. 


POSITION BLOCK FUNCTION (fc=4) 


The position block function, which is available to magnetic 
tape devices, allows you to poSition a referenced magnetic tape 
forward or backward one block. 


POSITION TAPE MARK FUNCTION (fc=6) 


The position tape mark function, which is available to mag- 
netic tape devices, allows you to: 


o Position a referenced Magnetic tape forward to beyond the 
next tape mark. 


Oo Position a referenced magnetic tape backward to ahead of 
the current tape mark. 


o Rewind to BOT 
o Rewind to BOT and unload 
BREAK NOTIFICATION FUNCTION (fc=9) 


This function, available only for KSR devices, is a request 
to notify the issuing task when a break occurs on a specific 
device. When a break does occur, the driver posts the break 
notification request and declares the device to be in break mode 
for the issuing task. 


In break mode, all I/O requests issued from the "broken" 
task are rejected, i.e., posted without any data transfers being 
Started. Execution of a subsequent break notification request 
will cause the driver to return to normal mode. 


Communications Function Codes 
The following function codes are for communications, and for 


interactive and noninteractive (such as card reader or printer) 
devices. 
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CONNECT FUNCTION (fc=A) 


This function provides the logical and physical connection 
between an application program and a communications device. The 
function may be used for noncommunications devices for program 
compatibility; i.e., no matter how these devices are connected to 
the computer, all interactive KSR and KSR-like devices, and 
noninteractive devices such aS card reader and printer, can be 
controlled by the same application program. 


See the Communications Processing manual for descriptions of 
the connect function, and disconnect function (described below), 
as they pertain to communications devices. 


DISCONNECT FUNCTION (fc=B) 


This function code provides the logical (normal and ab- 
normal) and physical disconnect between an application program 
and an interactive device. The function is processed as a no-op 
for noninteractive devices for program compatibility, i.e., a 
card reader or printer may be controlled by the same application 
program. 


The disconnect function as a logical function indicates that 
use of the indicated device is terminated. Termination may be 
either normal or an abort of all queued read or write requests 
issued only by this user program. 


DATA STRUCTURES 


Two data structures control the interactions among an appli- 
cation program, its device drivers, and the devices it uses. 
These structures are the input/output request block (IORB) and 
the resource control table (RCT). The IORB is the interface 
between the application task and the device driver; the RCT is 
the interface between the driver and its device(s). 


Input/Output Request Block 


The input/output request block (IORB) contains all informa- 
tion that a task requesting an I/O Service can specify to define 
the operation to be performed. In addition, it contains informa- 
tion returned by the driver to the requesting task concerning the 
outcome of its I/O request. 


The format of the IORB is shown in Figure 6-1; Tables 6-3 


and 6-4 define the individual IORB entries; these entries are 
common to drivers for all device types. Device-Specific IORB 
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information is provided in the separate device driver descrip- 
tions later in this section. 


NOTE: The labels (I CT2, I ADR, etc.) used in 
referring to the IORB entries are employed 
only for ease of presentation. The labels 
cannot be used for programming purposes. 


-1 eae |_RRB/I_SEM | 
; —_ 
SAF |_CTI 
1+$AF 1 CT2 
2+$AF | ADR 
2+2* SAF | RNG | 
3+2*$AF  1_DVS DEVICE SPECIFIC WORD 


4+2*$AF — I_RSR 


5+2* $AF | ST 


Figure 6-1. Format of I/O Request Block 
Table 6-3. Contents of I/O Request Block 


Contents 


0 through 15 Depending on the condition of the S- 

for SAF; or R-bits of I CTl, this word con- 

O through 31 tains a request block pointer (R-bit 

for LAF on), or a semaphore name (S-—bit on); 
set by user, used by system at ter- 
mination of request. 


O through 15;| Reserved for system use. l- or 
0 through 31 2-word pointer to indirect request 
block. 


0 through 7 Return status 


8 (T) This bit is set (on) while the re- 
quest uSing this block is executing; 
it is reset when the request termi- 
nates. System controls this bit; 
user should not change it. 
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Table 6-3 (cont). Contents of I/O Request Block 


Contents 


SAF I_ CTL 
(cont) (cont) 


. 


Wait bit - set if the requesting 
task is not to be suspended pending 
the completion of the request that 
uses this block. 


User bit. User may or may not use 
this bit; system does not change 
ch eee 


Release semaphore indicator. 
Values: O=No release, 1=ReleasSe on 
time-out of item named in I_ RRB. 


Must be zero. 


Return request block indicator. 
Values: O=No dispatch, 1=Dispatch 
of request block named in I_RRB, 
after time-out of this request. 
(System executes SROTSK, uSing 

I_ RRB, upon task termination. 


Delete IORB. Values: O=No delete; 
l=return IORB to dynamic memory 
pool where IORB is first entry of 
memory block. 


T/O bit - must be set. 


through 7 Logical resource number (LRN); 


identifies device to be used. 


(C) IBM-type request. Changes inter- 
pretation of I DVS to task word, 
and I_RSR and I ST to configuration 


words A and B respectively. 


Byte index; O=buffer begins in 
leftmost byte of word, l=buffer 
begins in rightmost byte. 


Reserved for system use. 


QO = Standard IORB; 1 = IORB is ex- 
tended at least 6+2*SAF items. 
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Table 6-3 (cont). Contents of I/O Request Block 


bese ae ge Net SP IS RET EE ST Le OE IE EE DY eA Sa Te ES I EEE) 


| 1+SAF ECT? C through F Function code. Driver function, 
(cont) (cont) See Table 6-1. 


2+SAF I_ ADR QO through 15 | Buffer address, SAF mode. 
(See Note.) 
0 through 31 
2+2*SAF 0 through 15 


3+2+*SAF| I DVS 0 through 15 
4+2*SAF | I_RSR 
5+2* SAF 0 through 15 


For break notification requests, the KSR driver 
Stores the TCB of the isSuing task in this word. 
When break occurs, the contents of thiS word are 


Buffer address, LAF mode. 
l- or 2-word pointer. (See note.) 


Range —- number of bytes to be 
transferred; used as input field 

for cartridge disk or disk storage 
unit. 


Device-specific information. 


0 through 15 | Residual range. Indicates the 
number of bytes not transferred. 
Filled in by the system on com- 
Pletion of the order. Used by 
cartridge disk and mass storage 
unit driver as a data offset © 


value. 


Status word. Reflects the map- 
Ping of the hardware status into 
software status format; used as 
input field high-order bits of 
sector number for mass storage 
unit. (See Table 6-4) 


transferred to the RCT. 
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Table 6-4. IORB Software Status Word' (I_ST) 


Bit Disk Storage 
Position ASR/KSR Card Reader Card Reader/Punch Printer Diskette Cartridge Disk Unit Magnetic Tape 


7 ee Se ee ee ee ee eee ee 
|: a CC CS 
Z Over /underrun Over /underrun Data service rate Over/underrun Over/underrun Over/underrun Retryable error 
error 
3 Even parity Mark Sense mode | Invalid ASCII nd of form | Deleted field Write protect Write/protect |Write protect 
error code error error error 


Se SS, 


f 5 
ae 
6 Long record External clock | Card jam Missed data Missed data Missed data. 
track synchronization | synchronization | synchronization 


Punch echo or 
read registration 


7 Checksum error Read check 6) Unsuccessful Unsuccessful Unsuccessful EOT 
search search search 
9 emination | ASCII code 0 Two sided Missed clock | Missed clock 
pulse pulse 
Missed sector Successful Nonretryavle 
pulse retry error 
Ee Ce 
ede 


0 
3 a 
ee : eo 


1. Nonexistent resource, bus parity, and uncorrected memory. 


errors are combined into bit 15 of IST, but each occurrence 
is noted separately in the RCT. 


h 
CC2 


ms 


Long record 


0) 


The online drivers will flag, in the RCT, corrected manory 
errors and driver or hardware corrected errors. 


TEguivalent to a modified status word 1. 


Resource Control Table (RCT) 

The resource control table (RCT) is a system-defined table 
that contains task or device parameters. A task RCT consists 
of a pointer to the interrupt save area (ISA) servicing the task. 
A device RCT contains a pointer to the interrupt save area 
servicing the task and the device-specific information shown in 
table 6-5. An entry in the logical resource table (LRT) points 
to the resource control table, thus establishing a correspondence 
between the logical resource none (LRN) and the interrupt Save 
area. 


Table 6-5 shows specific entries in the RCT. 


Table 6-5. Resource Control Table (RCT) Field Definitions 


Word | 
Offset ane 2 


—-SAF Pointer to TCB (and ISA) of Pee asa a ee ee ee, driver. 


Channel of the referenced device; set 
before driver initialization. 


Oa Device type as read from the device by 


the initialization routine. 


ia i 

rj rio 

KK 2) Oo bs 

UO ey) + (D 
cr Kw 
M O, 


2 Flags for use by the drivers. The first 
5 bits (0-4) are device specific. Flags 
that are dynamically modified by the 
drivers are indicated by an asterisk (*). 


R_TRCV (0) *(Tape) - Tape recovery requested. 


R_DDEN (0) * (Diskette) - Double density (set by 
AVR). 


R_IN (0) *(KSR) - Input attention to process. 


R_CRED (1) * (Tape) - Tape recovery successful. 


R_IBM(1) 


* (Diskette) - IBM type volume (set by 
AVR) 


R_BNVL (2) 


*(Tape) - Block count invalid. 


R_NFS (2) * Not connected to file system. 


R_FLSM(3) (For disk driver) - Large disk address 


(maSsS storage unit). 


R_FSCM(4) (For KSR) Not single character mode. 


eed 
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( Table 6-5 (cont). Resource Control Rable (RCT) Field Definitions 


Field Word 
(bits) Offset Content 


R_AVR (4) 2 (cont) (Disk) Do AVR when set. 


R FLDT(5) 


Disk type device. 


R_FLCM(6) Communication connected device. 


R_ FLSL(7) Slew type device. 


*Attention has occurred. 


R_FATN (8) 


R_FDOA(9) Disable device on attention. 


R_DSAB(A) *Device disabled. 


R_ELBZ (B) *Error log busy. 


(C-F) *The last four bits of status word one. 


| R STTS 3 Last hardware status word one. 


i R_ERLG Pointer to the error log structure or 
3 null (if error log is not active). 
R_ TIOT 4+SAF Timeout value (seconds). 


R_ FMSK 5+SAF The 32-bit mask defining the global 
action to be taken for a given function 
(see I CT2). The first word has a bit 
corresponding to function, set if the 
function for this device is illegal or 
no-operation. 

The second word will have the corre- 
sponding bit set for illegal function 
(e.g., read for printer) or special, 
globally handled functions (wait on 
line.) 


R_DRQ 7+SAF Pointer to driver's request handler. 
R_DRAT 7+2SAF Pointer to driver's attention handler. 
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Table 6-5 (cont). Resource Control Table (RCT) Field Definitions 


Field Word 
eel ae era a ee 
The [The following fields ar fields are device-sSpecific, for device ieee a i a 
Disk Specific : 


7+3SAEF Number of sectors per cylinder. For 
devices, depending on the media, it must 
be set by AVR. 


8+3SAF Number of sectors per track. 


9+3SAF Z'FFFF' for devices with the automatic 
track crossing Z'FEFF' for diskette. 


10+3SAF Z'O0800' for fixed cartridge disk, zero 
for others. 


KSR Specific | 


7+3SAF Configuration words A, 


9+3SAF Two-word unique identifier of task for 
| which "break" must inhibit messages. 


11+3SAF Pointer to single character mode buffer 
and its control structures. 


Magnetic Tape Specific | 


7+3SAF Status words two 


8+3S5AF Tape mark count 


9+3SAF Block count 
CALLER INTERFACE WITH DEVICE DRIVER 


To request execution of an I/O operation, the caller must 
issue a SRQIO macro call with $B4 pointing to the IORB that is 
to be serviced. If the IORB specifies synchronous I/O (W-bit 
reset), the issuing task will be suspended until the I/O opera- 
tion is completed. 


If IORB specifies asynchronous I/O, the instruction at the 
return point will be executed aS soon as the system queues the 
IORB on the driver's level. The application should issue a SWAIT 
macro call when appropriate for the asynchronous request. 
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Thus, upon return from the driver at the completion of the 
I/O operation, the caller must check the Rl register first to see 
if the request was successful. If there was an error it will be 
defined here. Hardware errors are defined in IORB entry I_ST 
(see Table 6-4). 


Residual range denotes how much of the requested data trans- 
fer was actually performed. If I _RSR equals Zero all data was 
transferred (see "Device Drivers" for details on device-specific 
basis). 


Those fields not shaded in Figure 6-1 must be initialized by 
the task requesting the I/O operation. The remaining fields are 
set by the driver in order to return information about the I/0 
request back to the caller or are controlled by the Monitor. 
Table 6-3 describes the purpose of each field. 


The channel number, defined at system building, is located 
in the device's resource control table (RCT) entry. (See the 
GCOS 6 MOD 400 System Building manual). The LRN supplied by 
the caller in the IORB serves as an index into a system table 
(LRT) which in turn contains the pointer to the RCT entry 
defining the device as in Figure 6-2. 


USER IORB LRT RCT ENTRY 


CHANNEL . 


Figure 6-2. LRN as Pointer to RCT 


Thus, with the LRN, the driver can indirectly access the RCT 
entry which defines the particular device the calling task wishes 
to access. 


The rest of the information needed to perform the I/O re- 
quest is found in the IORB itself. The caller-supplied standard 
function code in I CT2 is mapped by each driver into one or more 
device functions required to perform the actual request (e.g., 
read function code from disk translated by the disk driver into 
a "seek" to the correct track, and a "read" of the correct physi- 
cal sector). 


Finally a timer is started in order to protect against a 
device fault prohibiting the sending of a completion interrupt to 
the central processor. 


At the completion of any central processor-to-I/0O instruc- 
tion the driver can test the I/O flag in the indicator (I) regis- 
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ter in order to tell if the central processor instruction was 
accepted by the device. 


When the I/O operation terminates, the device interrupts the 
central processor at the level of the driver. The device knows 
which level to interrupt at since the corresponding driver trans- 
mitted the level value to the device itself prior to any I/0 
being performed. (Within the device ISA, the DEV field (see 
Figure 7-1) contains the channel number of the device and the 
interrupting level. Thus, the driver can explicitly tell which 
device is interrupting, and can perform the I/O completion 
processing.) 


DEVICE DRIVERS 


The remainder of this section discusses the device drivers 
in the following order: 


Card reader/Card reader-punch driver 
Printer driver 

Disk driver 

ASR/KSR driver 

Magnetic tape driver 


0000 0 


Card Reader/Card Reader-Punch Driver 


The card reader and card reader-punch devices are serviced 
by a Single driver. The driver uses only three function codes; 
i.e., read, write, and wait online. In addition, its IORB word 
I DVS can be coded to define the character code of the input; 
namely, ASCII or verbatim. These values are specified in the 
IORB as defined in Table 6-7. 


The translation/mapping of these codes from punched card 
format, into memory on reading, is described below. 


In addition to the standard driver functionality discussed 
earlier, this driver also: 


o Detects and discards unsolicited interrupts (Sea O upon 
entry to driver). 


o Detects an end-of-file condition and sets the appropriate 
return status (ASCII GS character in column 1 of any 
card=EOF). | 


o Detects "device not ready" condition and sets appropriate 
error condition. 
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ASCII MODE 


In this mode, punched cards are processed as Shown in Figure 
6-3. Each card column consisting of a 12-bit ASCII card code is 
converted into an 8-bit ASCII byte and stored in the main memory. 


The ASCII card code table as specified in American National 
Standard X3.26 is given in Table 6-6. Note that no multiple 
punches in rows 1 through 7 are allowed and thus the 12-bit card 
code allows a maximum of 256 unique codes to be defined. 


Translation is done by the card reader attachment which also 
provides a software-visible IORB status indicator that is set 
whenever an illegal ASCII card code is detected. This error con- 
dition is signaled by a 7 in Rl register if any card column read 
had a hole pattern which was not one of the legal hole patterns 
given in Table 6-6. The illegal card code causes an ASCII-EO 
(all 1's) code to be loaded in the main memory. 


COLUMN COLUMN 


N N+1 N42 
ee r7T1 FOI 
| ; pul 

Wy l 
| i | 

0 | | 
| | | | 

| | 
| | | | l 

2 | 

a | | | | 
| | 
CPt iis 

4 | 

l | | l 
| 

Eos a ly l 

et dt | 

ee. | | 

es: ee | 


HOLLERITH 
TO ASCII 


TRANSLATOR 


0 7 O 7 
aan aa aa | 
a ASCII BYTE N ASCILBYTEN+1] | N+2 | 
(oes So eed 
NOTES: 1. This translator will provide a status indicator which 


will be set whenever an illegal Hollerith code is read. 


2. The translator shown above is in the card reader 
attachment. 


Figure 6-3. ASCII Card-to-Memory Code Formatting 


6-17 CBO8 


81-9 


80d) 


Table 6-6. Hollerith-ASCII Code Table 


: 
12-11-9-8 | 12-11-0-9-6 | 12-11-8-7_| 12-11-0-8 | 12-11-9-8-4 


im 
Hie 
FFE 


bS 
COL 
b4b3b2b1| ROW 2 3 4 


0000 


oO 
— 
i 


P 
: 12-11-7 
1 


SCH DC1 | A 

12-9-1 11-9-1 12-8-7 | 1 12-1 : 

STX DC2 e 2 B 

2 12-9-2 11-9-2 8-7 2 12-2 
ETX DC3 x 3 fa . 
3 12-9-3 11-9-3 8-3 3 123 11-0-2 | 0-9-3 9-3 12-0-9-4 
; 
11-0-3 -4 9-4 


ENQ NAK te ° bE u 
5 0-9-8-S 9-8-5 0-8-4 5 12-5 4 12-0-5 11-0-4 
ACK SYN & 6 I t 
0-9-8-6 9-2 12 6 12-6 =) 
Pie ; } 3 i 


— 


_ oO 
“y FA) 


11-0-9-8-11 12-11-0-9-8-1| 12-0-9-1 


0-9-1 


ae) 
_ 
oo 

— Ne) 

pied ’ 

1 ~— 

© 

(oe) 

‘ 

to 


12-0-9-2 


d q 
12-0-1 12-11-8 
b ig 

1-9 12-0-2 12-11-9 


Cc 


11-8-1 12-11-0-9-7 12-11-0-9 | 12-11-9-8-5 
11-0-9-2 | 12-11-0-9-8 ] 11-0-8-2 | 12-11-0-8-2 | 12-11-9-8-6 


5”, 


0-9-2 12-0-9-3 2 


11-0-9-3 12-0-8-1 11-0-8-3 12-11-0-8-3 | 12-11-9-8-7 


PyM 
N 


3 


0-9 12-0-9-5 


11-0-9-5 | 12-0-8-3 11-0-9-8-3 | 5 
1 1-0-9-7 11-0-8-7 11-0-9-8-5 
11-0-9-8 12-0-9-8-2. } 11-0-9-8-6 
me oe 
ies anes 
nore wee 
[2as6 |raso7 | muses) ie 
12-11-0-9-5 | 12-11-8-6 | 12-11-0-7 | 12-11-9-8-3] 12-11-0-9-8-7 


e 
? Vv 
12-0-6 11-0-5 12-9-6 12-0-9-7 
P ‘ e 
-6 12-0-7 11-0-6 11-9-7 12-9-8 12-0-9-8 
H h X 
12-8 -7 12-0-8 i11-0-7 0-9-8 
HT — EM ) | i 
12-9-5 11-9-8-1 11-8- 12-9 0-8 12-0-9 
IF SUB ig : J Z | 
0-9-5 9-8-7 1 1-8-4 8-2 11-1 0-9 12-1 1-1 
VT ESC + ; K [ k | 
12-9-8-3 0-9-7 12-8-6 11-8-6 | 11-2 12-8-2 | 12-11-2] 12-9 0-9-8-3 
FF FS > < L ‘ ] 
12 12-9-8-4 1 1-9-8-4 0-8-3 12-8-4 | 11-3 0-8-2 12-11-3] 12-11 0-9-8-4 
CR GS - M ] m | 
13 12-9-8-5 11-9-8-5 11 11-4 11-8-2 | 12-11-4] 11-0 12-9-8-1 11-9-4 12-1 1-9-5 
SO RS . > N A n ~ 
14 12-9-8-6 | 11-9-8-6 12-8-3 0-8-6 | 11-5 11-8-7 | 12-11-5 | 11-0-1 12-9-8-2 9-8-6 12-11-9-6 
SI US i 9 O 7 ip) DEL 
15 12-9-8-7 1 1-9-8-7 0-1 0-8-7 | 11-6 0-8-5 12-11-6 | 12-9-7 11-9-8-3 11-0-9-1 1 2-11-9-7 


8-5 12-7 7 


oslo<l/ocio- 
Ww 


11-0-9-4 12-0-8-2 11-0-8-4 12-11-0-8-4 | 11-0-9-8-7 


e0 cof I~ 
Ox 


a4 e196 


0-9-8-2 


y 
11-0-8 


a. 


z 
1 1-0-9 12-11-9-2 


12-11-9-3 


12-9-4 12-1 1-9-4 12 


13 


15 


VERBATIM MODE 


In this mode, punched cards are processed as shown in Figure 
6-4. The card column pattern is stored in bits 4 through 15 of 
the main memory word with bits 0 through 3 set to zero. All 
2 hole patterns will be valid during a verbatim mode operation 
The device-specific fields in the IORB and RCT are given below. 


COLUMNS 


N 


COON MOARWNH ON 


i va a eS se ae 


0 34 ¥67 1S es 
read L2LOL}opanfolsf2}3fa|s[s] tafe} po 
sleeg tts 12/11 0/1]2]/3/4]/5{6]7 Be tach ie ata cuss bebe Be 
\ STR, AR \ennencncomemnrareD, smears 


WORD N WORD N+1 


Figure 6-4. Verbatim Mode Formatting 
CARD READER/ CARD READER-PUNCH DEVICE-SPECIFIC IORB FIELDS 


Table 6-7 defines the device-specific fields in the IORB not 
previously defined. 


Table 6-7. Card Reader Card/Reader-Punch 
Device-Specific IORB Fields 


a a tt 


I CT2 | Function code O=walit-on-line Refer to "Driver 

— l=write Functions and Func-— 
tions Codes" earlier 
in this section. 


Driver “reads" cards 
for "range" number of 
bytes. 


3=write file mark Driver "writes" cards 
for "range" number of 
bytes. 
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Table 6-7 (cont). Card Reader/Card Reader-Punch 
Device-Specific IORB Fields 


ET a EA ee ES TO RE LT EE) 


a a a eats ee oe ee 
If range is greater 


O<range<32K-1 
than card size, re- 


Sidual range will 
reflect the differ- 
ence. 


I RNG } Range 


0 i? to 2a. tO 


mode: Q=ASCII 
2=verbatim 


I_RSR| Residual range O<initial range Detects device | 
malfunction. 


CARD READER/CARD READER-PUNCH DEVICE-SPECIFIC RCT FIELDS 


Defines character set 
of data being read. 


Device-specific 


The following RCT fields contains device-specific values for 
the card reader and card reader-punch. 


Item Field Definition Use 
R_ TYP Device Type 2008-200F Card reader device type 
2088-208F Card reader-punch device 
type 


R STTS Device Status See Table 6-8 Status as read from device 
6-9 ° 


CARD READER/CARD READER-PUNCH RCT/IORB STATUS CODE MAPPING 
The card reader/card reader-punch controller returns to the 
driver various codes that are placed in the RCT. The status code 


is then made visible to the application by placing it in the IORB 
as shown in Tables 6-8 and 6-9. 
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Table 6-8. Card Reader IORB Hardware/Software 
Status Code Mapping 


Meaning If Bit Set 


Device ready 

Attention 

Data service rate error 
Mark sense mode 
40-column card mode 
51-column card mode 
External clock track 
Read check error 

ASCII code error 


Corrected memory error 

Nonexistent resource/fatal error 

Bus parity error/fatal error 
Uncorrectable memory error/fatal error 


Table 6-9. Card Reader/Punch Hardware/Software 
Status Code Mapping 


RCT TORB 
Word Word 
Rotts 7 i ST Meaning If Bit set 


Device ready 

Attention 

Data service rate error 

Invalid ASCII code 

Punch echo or read registration 
Light/dark check 


Card jam 


Corrected memory error 

Nonexistent resource/fatal error 

BuS parity error/fatal error 
Uncorrectable memory error/fatal error 
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Printer Driver 


The printer driver performs all data transfers to all line 
and serial printers as well as terminal print devices. Format 
control of printing is achieved by Supplying a control byte as 
the first entry in a data buffer. 


PRINT CONTROL BYTE 


A print control byte can precede text data sent to output 
"print" devices (e.g., console, printer, VIP, etc.). This byte 
must be the first character in the data buffer and is included in 
the range count of the IORB for the request. 


Forms control differs between printers (which uses prespace, 


then print format conventions), and consoles (terminals), (which © 


use print, then postspace format conventions). These are indi- 
cated separately below. 


The contents and meanings of the control byte are: 


pit; {oli 2]3]4 y 
FIELD: }Y} PP | V] COUNT | 


Action Caused | 


Line Printer Terminal Printer 


(Space Before Print) (Space After Print) 


O=Use IORB word I DVS for 
device-specific informa- 
tion 


l=Ignore IORB word I DVS 


OO Print; ignore V and Not Used. 
count/fields; single 
Space except at end- 
of-form, skip to head- 


of-—form. 


Don't print; perform 
actions defined in V and 
count fields. 


Print; perform actions 
defined in V and count 
fields. | 


Reserved for system uSe, 
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Action Caused 


Line Printer Terminal Printer 
(Space Before Print) (Space After Print) 
EERIE Ee Naa a Ne ON Fat RT a gr Sa Se LD | Sean ante ICR re OI ie NE RAT ra a ee ames a eer 
O Prespace according to O=No prespace. 
Count Field. 


If count = 0, skip to 1=Prespace three lines, 
head-of-form. If count count field must be 0. 
is between 1 and 12, and 

the VFU option is present, 

skip to the VFU channel 

defined by the count 

field. 


If count is greater than 
12, or there is no VFU 
option, do one prespace. 


The control byte summary is as follows: 
Code 


| Line/Serial Printers 


ASCII Resulting Action 


ESL) CRAIN REN CNIS DmeRRE ION (NIE NUD NPI IC RINIAE FRE Set vON pc EDIEIT SUEDE TIE NPT UIs Tae ny ett 7 UIE ON NE eaten ERIS ET ED Oy SARI IRC eR NL OSI SEE A nD RT EERE, 
Single space, then print; skip to head-of- 
form at end-of-form. | 


Space Count lines, don't print. 


Skip to VFU channel number in Count, don't 
print. 


Space Count number of lines, print. 


Skip to VFU channel number in Count, print; 
50 = skip to head-of-form. 


Reserved for future use. 


Reserved for future use. 
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No prespace, print. 


Prespace three lines, print. 


Reserved for future use, 


Reserved for future use. 


PRINTER DEVICE-SPECIFIC IORB FIELDS 


Table 6-10 defines the IORB fields whose contents are 
Specific to the printer driver. 


Table 6-10. Printer Device-Specific IORB Fields 


IORB Item Definition Use 


O=wait-on-line 
l=write . 


See "Driver Function 
and Function Codes." 
Driver will "write" 
from I ADR "range" 
number of bytes. 


I_RNG Range | | O<range<32K-1 If range is greater 
than line size re- 
Sidual range will 
reflect the 
difference. 

I DVS Device-specific 0 11 12 13 14 15 


1 
0 0 0 0 0 90 


F: O=Assumes line printer format 
control 


1=Assumes terminal format control 


All other bits must be zero. 
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{ TABLE 6-10 (cont). Printer ee IORB Fields 


M3 Software Status | Shown rea hace becca sees from RCT Wasned Exon RCT ward 
word ware status. 


For cases where original range is less nn or equal 


to line length, the value in the residual range has 
the following meanings: 


0 - Completed space/print operation. 

original range - Neither space nor print occurred. 
original range-l - Spacing occurred but no printings 
Other residual range values imply spacing and 
partial printing, 

The preceding implies modulo line length. 


PRINTER DEVICE-SPECIFIC RCT FIELDS 


The fields in Table 6-11 were not defined previously since 
they are device-dependent. 


g Table 6-11. Printer Device-Specific RCT Fields 


PS Pas BAe ee Sk eh che aR ne oe ah ne ae ge a | 


R_ TYP Device type 2000-2007 Identifies device type. 


R_STTS Device status | Shown below | Status as read from 
device. 


PRINTER RCT/IORB HARDWARE/SOFTWARE STATUS CODE MAPPING 


Table 6-12 indicates the hardware/software status code map- 
ping for printers. 
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Table 6-12. Printer RCT/IORB Hardware/Software 
Status Code Mapping 


RCT IORB 
R STTS|} I ST Meaning If Bit Set 


Device ready 
Attention 


End-of-form 


Corrected memory error 

Nonexistent resource/fatal error 

Bus parity error/fatal error 
Uncorrectable memory error/fatal error 


Disk Driver 


A single disk driver supports the following disk devices: 
diskette, cartridge disk, and mass storage unit. 


DISK DRIVER PROCESSING FOR DISKETTE 


Disk driver processing for diskette is as follows: 


O 


The driver does not explicitly reference the volume id of 
the diskette; therefore, you must ensure that volumes 
addressed are on the proper drives. 


All sector addresses used in the IORB are relative to 
track O/sector 0. 


The driver converts the volume relative sector number, 
defined in the IORB, into physical track and sector 
numbers, which it then sends to the device to define the 
operation. It does this by dividing the sector number by 
26, which is the number of sectors/track on a diskette. 


The driver can Support more than one diskette device, as 
long as each device is configured at a different level. 

The reason for this is that each device requires an RCT 

and there is only one RCT per level. 
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Note that a diskette sector is 128 bytes long. If 

range is less than 128 bytes, a write command will zero 
fill the rest of the sector. If range is greater than 
128 bytes on either a read or a write, the driver will 
read/write multiple sectors including switching to the 
next adjacent track, if necessary. Thus, from a uSer 
point of view, a read or write request for "range" number 
of bytes will take place regardless of the number of 
physical sectors or track switches involved. 


If hardware errors occur, the operation (seek or read/ 
write) will be retried up to eight times (four rereads 
and four rereads with recalibrate). 


If the device is not ready, a return status of "device 
not ready" (5) will be returned. 


Diskette Device-Specific IORB Fields 


Table 6-13 defines diskette device specific IORB fields not 
previously defined. Other IORB fields are as already defined. 


I cT2 


specific number 


Table 6-13. Diskette Device-Specific IORB Fields 


Definition 


Function code O=wait-online Previously defined. 


l=write data Driver performs appro- 
2=read data priate I/0 commands to 
E=read disabled | transfer the data. 
device 


physical track number and 
physical sector number on 
the track. 


I_ DVS Device- Relative sector | Driver converts this to 


< original Residual range will 

range always be equal to zero 
(i1.e., transfer com- 
pleted) unless there is 
either a hardware mal-— 
function, or invalid 
track number accessed 
during a extended read or 
write operation. 


6-27 CBO08 


Diskette Device-Specific RCT Fields 


The fields in Table 6-14 were not defined earlier due to 
their device-specific nature. 


Table 6-14. Diskette Device-specific RCT Fields 


R_ TYP Device type 2010-2017 Identification of device. 


R_ STTS Shown below |StatusS word 1 as read from 
device. 


Diskette RCT/IORB Hardware/Software Status Code Mapping 


| Table 6-15 indicates the hardware/software status code 
mapping for diskette. 


Table 6-15. Diskette RCT/IORB Hardware/Software 
Status Code Mapping 


RCT ITORB 

R STTS | I_ ST Meaning If Bit Set 
fe ates 52th ot ees Mh ce BS at Pi es Na ee ee oO 
Device ready 
Attention 
Data service rate error 
Deleted file 
Read error 
Device fault 
Missed data sync 
Unsuccessful search 


mrNNUOBWNHOF OC 


Seek error 

Corrected memory error 

Nonexistent resource/fatal error 

Bus parity error/fatal error 
Uncorrectable memory error/fatal error 


2 
3 
4 
= 
6 
7 
10 
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DISK DRIVER PROCESSING FOR CARTRIDGE DISK 


Disk driver processing for cartridge disk is as follows: 


O 


O 


Sector size is 256 bytes. 


The driver does not explicitly refer to the volume id of 
the disk; you must ensure that the volumes addressed are 
on the proper drives. 


All sector addresses used in the IORB are relative to 
cylinder 0, track 0, Sector 0. 


The driver converts the volume relative sector number, 
defined in the IORB, into physical cylinder, track, and 
sector numbers, which it then sends to the device to 
define the operation. It does this by dividing the 
sector number by 24, which is the number of sectors/track 
on the disk. 


Cartridge disk requires two RCTs, one for the fixed and 
one for the removable platter; each platter has.its own 
LRN. 


Cartridge disk driver logic combines seek and data trans- 
fer functions. When errors occur, eight attempts are 
made to correct an error, four Sseek/data transfers and 
four seek/data transfers with recalibrate. 


Offset read (not write) capability is provided by speci- 
fying the desired displacement in the I_RSR field of the 
ITORB. 


The offset read and offset write capabilities are not 
provided. 


When the driver notes a change in the ready state, it -is 
disabled the device (by a software switch) and notifies 
the file manager, which executes the automatic volume 
recognition procedures. 


see the Data File Organizations and Formats manual about 
data format on cartridge. 


Cartridge Disk Device-Specific IORB Fields 


The fields in Table 6-16 are specific to cartridge disk; all 
other fields are previously defined. 
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Table 6-16. Cartridge Disk Device-Specific IORB Fields 


TORB | 
Pac al a Definition Use 
Frid ch Nae eaten eh aan eS et een An Goh fe Ee atte Lian ee tp al) 


Specifies I/O operation. 
A read with range of zero 
performs a verify of the 
selected sector, with no 
data transfer to memory. 


Function ene ee O=Wait online 


l1=Write 
2=Read 


E=Read disabled 
device 


Driver converts this to 
physical cylinder, track, 
and sector number in order 
to locate the data needed. 


I ST Software See Table 6-22 Hardware status from disk. 
status word 


I_ RST | Residual 0< original Prior to a read, an offset 
range value may be specified 
here so that reading can 
begin at other than the 
physical sector boundary; 


Relative sector 
number 


I DVS | Device 
Specific 


after I/O operation the 
Field contains the number 
of bytes not transferred 
in the operation. 


Cartridge Disk Device-Specific RCT Fields 


Table 6-17 defines the RCT fields whose contents are speci- 
Fic to the online cartridge disk driver. 


6-30 CBO8 


S 
Nid 
Se 


Table 6-17. Cartridge Disk Device-Specific RCT Fields 


RCT Item Definition 


Device type. The values are: 2330-2333, and have 
these meanings: . 


2330 Low density, removable only 
2331 Low density, removable and fixed 
2332 High density, removable only 
2333 High density, removable and fixed 


S STTS Device status; see Table 6-18. 
R FXPL Bit 15 is set if this RCT is for a fixed platter. 


Cartridge Disk RCT/IORB Hardware/Software Status Code Mapping 


Table 6-18 indicates the hardware/software status code map- 
ping for cartridge disk. | 


Table 6-18. Cartridge Disk RCT/IORB Hardware/ 
Software Status Code Mapping 


RCT ITORB 
R STTS |1I_ ST Meaning If Bit Set 


Over or underrun 
Write protect error 
Read error 

Illegal seek 


Missed data synchronization 
Unsuccessful search 

Missed clock pulse 

Missed sector pulse 

Seek error 


OONANNHBPWNHH © 
row Wry aojm BWDHBD i! 


Fatal error 
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DISK DRIVER PROCESSING FOR MASS STORAGE UNIT 


Disk driver processing for the mass storage unit is as 


follows: 


O 


O 


Sector size is 256 bytes; there are 64 sectors per track. 


The driver does not explicitly refer to the volume id of 
the disk pack, so you must ensure that the volumes ad- 
dressed are on the correct drives. 


All sector addresses in the OIRB are relative to cylinder 
0, track 0, sector 0. There are four models: 


5 tracks per cylinder 
411 cylinders 
823 cylinders 


19 tracks per cylinder 
411 cylinders 
823 cylinders 


The driver converts the volume relative sector number, de- 
fined in the IORB, into physical cylinder, track, and sector 
numbers, which it then sends to the device to define the opera- 


tion. 


It does this by dividing the sector number by 64, i.e., the 
number of sectors/track on a disk. 


O 


O 


The mass Storage unit requires only one RCT, and one LRN. 


The driver combines seek and data functions. When errors 
occur, eight attempts are made to correct the error, 

four seek/data transfers, and four seek/data transfers 
with recalibrate. 


Offset read (not write) capability is provided by spec- 
ifying the required displacement in the I_RSR field of 
the IORB. 


The offset read and offset write capabilities are not 
provided. 


When the driver notes a change in the ready state, it 
disables the device (by a sofware switch) and notifies 
the file manager to execute the automatic volume recog- 
nition procedures. 


See Data File Organizations and Formats manual about data 
formats on the mass storage unit. 


6=32Z CBO8 


Mass Storage Unit Device-Specific IORB Fields 


The fields in Table 6-19 are specific to the mass storage 
unit; all other fields are as previously defined. 


Table 6-19. Mass Storage Unit Device-Specific IORB Fields 


FES a TN Sn a Pee Mt ea Nh a et ses ee eee ee | 


ETE aE RRS aan (PEW SPAS MRE Str aN SO gh A SR REESE) (SION eT Pen RNR UIE Ge ETS 
Specifies I/0 


L CrZ Function Code O0=Wait online 
operation. 


1=Write 
2=Read 


E=Read disabled 
device 


Driver converts 
this to the physi- 
cal cylinder, 
track, and sector 
number in order to 
locate the data 
needed. 


Relative sector 
number 


Device-specific 


Residual range O4original range | After an I/O opera- 
tion, the field 
contains the number 
of bytes not 


transferred. 


Software status | See Table 6-21 


word 


Prior to an order, 
this field contains 
the high-order sec- 
tor bits of the 

I DVS field. After 
the operation, it 
contains the hard- 
ware status from 
device. 


Mass Storage Unit Device-Specific RCT Fields 


Table 6-20 defines the RCT fields whose contents are speci- 
fied to the disk driver for mass storage units. 
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Table 6-20. Mass Storage Unit Device-Specific RCT Fields 


RCT Item | Description 


Device type. The values are: 3360-2963; and have 
these meanings: 


2360 411 cylinders, 5 tracks/cylinder 
2361 823 cylinders, 5 tracks/cylinder 
2362 411 cylinders, 19 tracks/cylinder 
2363 .823 cylinders, 19 tracks/cylinder 


R STTS Device status; see Table 6-21. | 


Mass Storage Unit RCT/IORB Hardware/Software Status Code Mapping 


Table 6-21 indicates the hardware/software status code 
mapping for the mass storage unit. 


Table 6-21. Mass Storage Unit Status Code Mapping 


RCT TORB 
R_STTS | R_ST Meaning If Bit Set 


Over-/underrun 

Device fault 

Read error 

Illegal seek 

Missed data synchronization 
Unsuccessful search 

Missed clock pulse 
Successful recovery 
Reserved 


roo WDOrnyannwswwhd i 


0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
ta 
12 
13 
14 
15 


Fatal error 


ASK/KSR Drivers 


The standard directive DEVICE is used at system building to 
configure a KSR or ASR terminal. The keyboard/printer functions 
of an ASR are Supported; the paper tape reader/punch functions 
are not. Thus, the k-field within I DVS word (Table 6-22) must 
be zero. 
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To examine the first character of a message sent in single 
character mode (from a local KSR terminal) before the rest of the 
message is transmitted, proceed as follows: 


1. Issue a Single charactor asynchronous read with no echo 
to the terminal. 


2. When the read is completed, examine the character; then 
if the rest of the message is wanted, write the charac- 
ter to the terminal (with no carriage return or line 
feed). 


3. Issue a read for the rest of the message (with echo). 


Note that the operator terminal (keyboard/printer), when used, 
must be configured at LRN=0. For information about dialog with 
the operator's terminal, see the Operator's Guide. 


Character codes, function codes, and device control avail- 
able for the keyboard/printer are described below. 


KEYBOARD INPUT 


o Keyboard input is accepted until end-of-range, or car- 
riage return, whichever occurs first. The carriage 
return character is not indicated as part of the input 
data. 


o Keyboard control (line feed, carriage return, etc.) is 
definable in the IORB. 


o Editing characters can control input: 
@ Deletes the previous character entered. 
(control X) (an ASCII CAN code) 


\ Deletes all the previous characters entered on the 
same input line. 


NOTE: Since CAN is a nonprinting character, the *DEL* 
are displayed on a separate line when CAN is 
Struck. Further input may begin after completion 
of the DEL output. 


Causes character immediately following (@, CAN, 
CR, and\), to be treated as data input and not as 
editing characters; the back slash itself is not 
placed in memory. 
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PRINTER OUTPUT 
o Printer output is accepted until end-of-range. 


o Time-out period for keyboard/printer operation is 5 
minutes. 


ASR/KSR DEVICE-SPECIFIC IORB FIELDS 


Table 6-22 shows the values of device-specific fields for 
ASR/KSR devices. 


Table 6-22. ASR/KSR Device-Specific IORB Fields 


a Definition 
Keyboard/ 
TORB Item |Field Printer Use 


I CT2 Function code | l=write A=Connect Used by driv- 


2=read B=Disconnect | er to com- 
I_ DVS 


3=break ; plete the 
notifica- description 
of the re- 


quested I/0 
function. 


8 9 10 11 12 13 14 15 
DK E L C 0 A HB 


Device- 345 
Specific SFT 


Must be zero. 
Assumes line printer format control. 
Assumes terminal format control. 


Use control characters as defined to 
adapter. 


Treat all characters as data; 
no special character action. 


perform 


Stop output operation immediately upon 
"attention" detection if the detected 
character has a No Stop Bit status (é€.9., 
a "Break" key). 


Post "attention" but allow output data 
transfer to complete. 


Read attention character with input (if 
present). : | 


6-36 CBO08 


c Table 6-22 (cont). ASR/KSR Device-Specific IORB Fields 


DefEinition Use 
Keyboard/ 
TORB Item ield Printer 
ES a eR ee RE 


I_ DVS Device =] Discard attention character on input. 
(cont) (cont) 


Transfer to keyboard/printer. 
Do not echo keyboard input. 
Echo keyboard input. 
No line feed at end of transfer. 
Line feed at end of transfer. 


Carriage return at end of 
transfer. 


No carriage return at end 
of transfer mode. 


Must be zero. 
Disconnect without phone hang up. 
Disconnect with phone hang up. 


NOTE: The MDC-connected ASR/KSR driver 
does not check this bit. 


Software 
Status 
word 


fof Mapped by 
driver from 
the hardware 
status in 
order to 
tell re- 
questing 
task the 
hardware 
Status of 
the I/0 
operation. 


ASR/KSR DEVICE-SPECIFIC RCT FIELDS 


The fields in Table 6-23 were not defined earlier due 
to their device-specific nature. 
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Table 6-23. ASR/KSR Device-Specific RCT Fields 


A aA ELAR (ESRI PS PR Na NAC dR NU a gC REN a ND EE PO RO 
- Identifies device type; value 


R_ TYP Device Status/| 2018-201F 
read from device at initiali- 


zation time. 


R_STTS Device Status] Shown below | Last status word read from 
device. 


The following kinds of processing data are kept in the RCT 
workspace for the terminal. 


o Configuration word A 
o Configuration word B 


Oo Identifier for last task to receive a "break" from this 
terminal 


ASR/KSR RCT/IORB HARDWARE/SOFTWARE STATUS CODING MAPPING 


Table 6-24 indicates the status code mapping for ASR/KSR 
devices. 


Table 6-24. ASR/KSR RCT/IORB Hardware/Software 
Status Code Mapping 


Meaning If Bit Set 


| Device ready 
Attention 

Data service rate error 
Parity error (even) 


No stop bit 
Long record 
Checksum error 

Control character number 2 termination 
Control character number 3 termination 


bomb wnoro 


Corrected memory error 
Nonexistent resource/fatal error 

Bus parity error/fatal error 
Uncorrectable memory error/fatal error 
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Magnetic Tape Driver 


The magnetic tape driver manages all standard data transfer 
requests to and from 9-track phase encoded (PE), and 7- and 
9-track nonreturn to zero inverted (NRZI) tape drives on one or 
more magnetic tape controllers. The tape drive characteristics 
Supported by this tape driver are shown in Table 6-25. 


Figure 6-5 illustrates 6-bit and packed modes on 7-track 
tape and in memory in the transfer of data between the tape 
device and memory. 


Data on Tape 


aaaaaanp 


Data in Memory 


O0Oaaaaaadodobbobobobsb 


a, b, c = data bits 
p = parity bits (odd or even) 


bbbbbbp 


6-bit mode on 7-track (read tape into memory) 


Data in Memory 


X Xaaeaaaaxxbbobob ib 
MO Ce eS Ss ks me we Se me OC 


Data on Tape 


bbbbbbp 


LY) 


a, b, c = data bits 
Xx = ignored bits 
P = parity bits (odd or even) 


6-bit mode on 7-track tape (write tape from memory) 


Figure 6-5. Packed and 6-Bit MOdes on 7-Track Tape 


6-39 CB08 


Data on Tape Data in Memory 


a, b = data bits 
X = ignored bits 
p = parity bit (odd) 


Packed mode on 7-track tape (read tape into memory) 


Data in Memory Data on Tape 


00bbbbp 


= data bits 
= parity bits (odd) 


5) 
TO 
1 | 


Packed mode on 7-track tape (write tape from memory) 


Figure 6-5 (cont). Packed and 6-Bit Modes on 7-Track Tape 


Table 6-25. Characteristics Of Supported Tape Drives 


Density 
(bpi) Parity Mode 
even | packea|s-ait | 


LSE! SENSIS (SSUES ESSE 
s = X = = = 

ais X = ms i 

X X X X X 
"The application program must provide for tape positioning, 


creation and interpretation of labels, tape marks, control 
information, and data contents. 


Tape Drive 
Type 


m 
Nn 
~ 
Ol 
—! 
Ov 
>) 
© 
©O 
© 
© 
O1 
ox) 
o>) 
NO 
© 
© 


6-40 CB08 


The driver provides the following callable functions: 
o Wait online 

o Write 

o Read (forward) 

Oo Position block (forward and backward) 


o Position forward or backward by tape mark, rewind to 
beginning of tape (BOT), rewind to BOT and unload. 


The driver operates in the following modes: 
o Odd parity (9-track tape only) 

o Odd parity 6-bit (7-track tape) 

o Even parity 6-bit (7-track tape) 

o Packed, always odd parity (7-track tape) 


o Minimum data block, MDB (American National Standard 
specifies 18 or more characters per block in write, 8 
or more in read) 


o MDB-inhibited (If fewer than the specified number of 
characters must be read or written, this mode is 
required.) 


If MDB mode is specified for a write and the range is less 
than 18 characters, a parameter error is reported. If MDB mode 
is specified for a read and the range is less than 12 characters, 
the user will receive the first portion (requested range) of the 
First valid block and an unequal length check. If a "Short 
record" is detected, a corrected media error iS reported in 
Status word, I ST. If a record of less than 18 characters is 
written or less than 12 characters is read, the inhibit block 
size check bit (bit 12 of the device specific word, I DVS) must 
be set. 


Beginning of tape (BOT), end of tape (EOT), and end of file 
(EOF) conditions are reported for appropriate user action. If an 
error occurs in a case when the operation can be retried, the 
driver backspaces and reissues the order up to eight times before 
reporting a hardware error. If an error occurs and no retry is 
possible, the driver rewinds and forward spaces to the problem 
block and reissues the order once before reporting a hardware 
error. The driver does not check the tape volume identifier. 
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The EOT return Status is not returned for read operations; 
only the EOT status word bit is set. It is assumed that appro- 
priate application software conventions will prevent reads that 
would force the tape off the end of the reel. 


The resident magnetic tape driver is interrupt driven and 
must execute with a resident Monitor and with the central pro- 
cessor in the privileged state. It can support, on an adapter, 
one data transfer simultaneously with one or more rewind/rewind- 
unload orders. 


MAGNETIC TAPE DEVICE-SPECIFIC IORB FIELDS 
The IORB fields defined in Table 6-26 are specific to magne- 


tic tape devices. All other IORB fields are defined in previous 
subsections. | 


Table 6-26. Magnetic Tape Device-Specific IORB Fields 


tb Cr2 Function code 


ait online 


rite filemark 
osition by block (see range) 
osition file (see range) 


W 
W 
Read 
W 
P 
Pp 


Ol & WHF © 


I_Dvs 0 12 


50000000000 0|r [mode 


I: O=Normal American National Standard 
block sizes 


Device specific 


l=Inhibit sensing for American 
National Standard block size 


modes 0 = 9-track tape; or 7-track 
in odd parity 6-bit mode 


1 = 7-track tape in even 
parity 6-bit mode 


7-track tape in packed 
mode 
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( Table 6-265 (cont). Magnetic Tape Device-Specifiec IORB Fields 


Field a ee 


I rT RSR- Range Write: 1 Pyeite. Liieough EEF ~~~OC~«;3 PSCti<i=CtCSC 7FFF 


Read: O means verify; 1 through 
7FFF,, is valid 


Position by block: Negative is backspace 
O is illegal 


Positive is forward 
space 


Position by file: -2 Rewind unload 
—l Rewind 


0 Backspace to 
tapemark 


Forward space to 
tapemark 


F Nonzero when physical block exceeds 
a range. 


A read with a range of zero verifies the selected sector 
with no data transfer to memory. 


MAGNETIC TAPE DEVICE-SPECIFIC RCT FIELDS 
The device-specific fields in an RCT for magnetic tape de- 
vices are given in Table 6-27. 


Table 6-27. Magnetic Tape Device-Specific RCT Fields 


Definition 


Device type; values are 2045 207A 


Status word 


Tape status word 2 
Tape mark count 
Block count 


MAGNETIC TAPE RCT/IORB HARDWARE/SOFTWARE STATUS CODE MAPPING 


( The hardware/software status code mapping for magnetic tape 
- devices is shown in Table 6-28. 
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Table 6-28. Magnetic Tape RCT/IORB Hardware/Software 
| Status Code Mapping 


RCT ITORB 
R STTS |I_ ST Meaning If Bit Set 

SETAE EEO ND IIIT AAO ER LR ES et ARNE EID PSE DE RINNE INI SIE ESI FAI SHE TRIE SIT A OLY PLA A NS BE NOR STORE AIDE AAAI DAMES OUT ONO, 
Device ready 
Attention 
Rewinding 
Error - Operation can be retried 

MBZ 

Write protected 

Corrected media error 

Tape mark 

BOT 

EOT 

Unequal record length 

Error -— Operation cannot be retried 

10 MBZ 

11 Operation check 

= Corrected memory error 

12 High density 

5 Nonexistent resource/fatal error 

Bus parity error/fatal error 

Memory error - correction impossible/fatal error 


pwWtlNHOe tl 


WOODMAN A UA | WHI HO 


Oo CO ~1 OV | 
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SECTION 7 


TRAP HANDLING 


A trap is a special software- or hardware-related condition 
that may occur during execution of a task. The Level 6 hardware/ 
firmware responds to many trap conditions. The design of any 
application program should provide that when a trap occurs, the 
hardware/software response will include calling a dedicated soft- 
ware routine (a trap handler) to react to the trap. When trap 
handlers are provided, handling the trap is invisible to the task 
that caused the trap. | 


See the System Building manual for detailed information 
about the system building directives that are referred to below. 


Using the trap facilities of Level 6 hardware/firmware and 
the Honeywell trap handlers (Floating-point and Scientific Branch 
Simulators) require that you: 


o Provide enough trap save areas (TSA'S) in the system 
memory pool, by coding a value for the TSA parameter of 
the CLM directive SYS. The default value for this 
parameter results in six TSA's. 


o Include any Honeywell-supplied trap handlers, and any 
user-written generalized trap handling routine, in your 
configured software. These are the initial trap 
handlers. . 


Oo Provide a generalized trap handling routine (see Table 
7-1). The code for each task must identify this trap 
handler by providing its address in the STRPHD macro 
call. 


o On a task-by-task basis, enable all the trap numbers to 


be handled for the task, by including a SENTRP macro call 
in the code for each task. 
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TRAP CONDITIONS DURING TASK EXECUTION 


A trap handler that was configured at initialization time 
(by a SYS directive with an SSIP, CSIP, or DSIP argument, or by 
an LDBU directive) will handle a trap as follows. If more than 
one trap handler is connected to the same trap, the order of 
their execution is: (1) LDBU-created trap handlers are executed 
first, in reverse order of their definition. (2) SYS directive- 
created trap handlers are executed following execution of any 
LDBU-created trap handlers. 


The trap may then be handled (i.e., passed along) by a 
series of trap handlers. If those trap handlers do not handle 
the trap, one of the following conditions (trap enabled or trap 
not enabled) occurs, according to whether the trap number of the 
trap condition was enabled by the task. 


Trap Enabled 


If the task's code contains the SENTRP macro call with the 
pertinent trap number for this condition, the trap handler is 
invoked to execute at the priority level of the task in which the 
trap occurred. The trap handler responds to the trap, and exits 
via an RTT instruction to return to the task's code at the next 
sequential instruction following the one that caused the trap. 
The trap handler always runs in privileged mode. 


Should another trap condition occur during the execution of 
the handler the sequence is repeated unless the nested traps are 
the same type, in which case the sequence is as described for 
traps that are not enabled. 


Trap Not Enabled 


When a trap condition occurs in task code that has not en- 
abled this particular trap, an error message is written to the 
error-out file; the delete bit in the task control block is 
reset, the task is terminated, but the task's resources (memory 
and peripherals) are not released. Thus, a memory dump can be 
taken so that the error condition can be examined. 


The usual way to continue processing after a trap-not- 
enabled condition is to issue a new process (NPROC) command 
against the group containing the terminated task. 


CONTENTS OF TRAP-RELATED MEMORY AREAS 


In examining a dump to determine the nature of a trap condi- 
tion, check particularly the contents of the TSA. The trap 
handling mechanism is illustrated in Figure 7-1; the contents of 
the trap save area are described in the following pages. 


oe CBO8 


HARDWARE- 
DEDICATED 
MEMORY 
LOCATIONS 


0000 


LU 


NATSAP 


0010 


OO7E TV =2 


OO7F TVz1 


aoen | iv 
0081 | ivar | oe 
0082 | 1V=2 1SM 

RFU 


OOBF | IV #63 


AVAILABLE TSA'S 


TSA 


TSAL 


ETC. 


TRAP 
TSA HANDLER 
INSTR. 
TASK 
. 
= 
= 


OPT. 
WORK 
SPACE 
NATSAP POINTER TO NEXT AVAILABLE TRAP SAVE AREA 
TSA x TRAP SAVE AREA 
TSAL ms TRAP SAVE AREA LINK 
TV TRAP VECTOR 


Figure 7-l. 


Trap Save Area 
resides in the 
next trap save area in the 
trap Save area in the pool 
When the trap save area is 
interrupt save area), TSAL 


Link (TSAL) 
"available" 


INTERRUPT VECTOR 
INTERRUPT SAVE AREA 


Trap Handling Mechanism 


- When the trap Save area 
pool, TSAL points to the 
pool; the TSAL of the last 
contains a null pointer. 

in use (1.e., connected to an 
contains a null pointer (if 


this is the only or last, trap save area connected to 
this interrupt save area) or it points to the next trap 
Save area connected to this interrupt save area. 
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I-Register - The contents of this register are saved by 
hardware/firmware when a trap occurs. This register is 
then available for use by the trap handler. The high- 
order byte contains the quantity (40,, - trap number). 
This byte is stored by software on Models 33, 6/34, 6/36 
central processors, and by firmware on Models 43 and 47 
processors. 


R3-Register - The contents of this register are Saved by 
hardware/firmware when a trap occurs. This register is 
then available for use by the trap handler. 


Instruction - The hardware/firmware stores the instruc- 
tion associated with the trap. If a multiword instruc- 
tion is involved, the first word is saved. 


Z-Word - This word contains miscellaneous information 
relative to the trap. The format of this word is shown 
below: | 


BIT: 01 34 789 11 12 15 


Rlooo} er fpxoo of] is 


If R=0, the saved contents of the A-word are meaning- 
ful relative to this trap condition; if R=1, the saved 
contents of the A-word are not meaningful. 


BI 


4-bit field that is meaningful only when an indexed 
bit or byte instruction is associated with the trap. 
If an indexed bit instruction is involved BI indicates 
the four low-order bits of the associated index reg- 
ister; bit 7 of BI stores the least Significant bit. 
If an indexed byte instruction is involved, bit 4 of 
BI indicates the least significant bit of the as- 
sociated index register and bits 5 through 7 are 
zeros. 


PR 


The privilege state of the task was running when the 
trap occurred. 0 = nonprivileged state; 1 = privi- 
leged state. The value is taken from the P-bit of the 
S-register. 
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Is 


The length (in words) of the instruction associated 
with the trap. If a multiword instruction is involved 
and the trap occurs before the entire instruction has 
been fetched, IS indicates the number of words that 
were fetched, before the trap. 


o A-Word. In many cases, this word contains an address 
associated with the trap. (This word is not meaningful 
if bit 0 of the Z-word contains a 1.) The nature of the 
Saved address is governed by the specific trap condition 
and the specific instruction associated with the trap. 
Details relative to each trap condition are in Table 7-1. 


o Program Counter - The contents of the program counter are 
Saved by the hardware/firmware when a trap occurs. This 
is the address to which a return iS made when the trap 
handler completes. In most cases the program counter 
will point to the instruction or location following the 
instruction associated with the trap. However, when an 
input/output instruction is involved, the program counter 
may point to an address within the instruction; in this 
case, the trap handler must modify this word before 
issuing a return to "normal" task processing. 


o B3-Register - The contents of this register are saved by 
hardware/firmware when a trap occurs. This register is 
then available for use by the trap handler; as the trap 
handler is entered, the B3-register points to the A-word 
in the trap save area. 


Trap Save areas (TSA's) are 64 words long in SAF mode, and 
104 words in LAF mode. The discussions about memory dumps in the 
Program Execution and Checkout manual include discussions about 
optional work space used by trap handlers and about saving regis- 
ters for a Monitor macro call. 


Pointer to Next Available Trap Save Area _ (NATSAP) 


Memory location 0010,, (NATSAP in Figure 7-1) points to 
the first trap save area in the "available" pool. If there are 
no trap save areas in this pool, NATSAP contains a null pointer. 


When a trap occurs, hardware/firmware examines the pointer 
in NATSAP to ascertain the address of the start of the trap Save 
area in which information will be stored for use by the trap 
handler (if any) that reacts to the trap. 
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Trap Vector 


A trap vector is a hardware-dedicated memory location that 
can be used to point to the entry address of a trap handler. 
Each trap vector is associated with a specific trap condition and 
can point to only one trap handler's entry address. 


Trap Save Areas 


Initially, when processing of an application begins, all 
trap save areas exist in a linked "pool", which is pointed to by 
memory location 0010,, (NATSAP in Figure 7-1). All trap save 
areas remain in this pool until a trap condition occurs within a 
running task, at which point the hardware/firmware (1) stores 
information in the first available trap save area in the pool, 
(2) links this trap save area to the interrupt Save area for the 
priority level of the task that was running when the trap oc- 
curred, and (3) unlinks this trap save area from the pool. 

Later, after the trap handler (if any) has completed its work, 
the trap save area is returned to the pool of available trap save 
areas. Thus, at any time, a given trap save area is either in 
the pool of available trap save areas or in use because of a trap 
condition 


The trap save areas reside in the system pool. 


Interrupt Vector 


An interrupt vector is a hardware-dedicated memory location 
that (if "connected") points to the second entry of the interrupt 
Save area for a Specific priority level. (See Figure 7-1, where 
interrupt vector 1 is pointing to an interrupt save area.) 


Interrupt Save Area (ISA) 


An interrupt save area is a block of memory in which hard- 
ware/firmware performs a context Save when a interrupt occurs. 


When a trap occurs, if the appropriate trap handler is 
available in the application, the first word (TSAP) of the inter- 
rupt save area (for the current priority level) is set to point 
to the link word (TSAL) of the trap save area in which hardware/ 
firmware has just stored information relative to the trap (see 
Figure 7-1). TSAP is subsequently used by the trap handler to 
gain access to the trap Save area. 
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Monitor call; 
implicitly handled 
by the operating 
system 


1 

Software trap 
Z 

Breakpoint instruction 
3 


| Scientific floating 


point operation when 
SIP hardware not in 
system 


Table 7-l. 


Contents of Selected Words of Trap 


Save Area When Trap Occurs 


Specific Event Saved Instruction Saved 2Z-Word 


B 
| MCL instruction 
| BRK instruction 


Scientific instruction whose 
address expression generates 
a reference to a register 


Scientific instruction whose 


0001 


Unspecified 


Instruction that 
caused trap 


Saved A-Word 


80xl 


Unspecified 


Saved ; 
Program Counter 


Next location 


Unspecified 


First word on in- 


Effective address 


Next location 


Unspecified 


instruction 


generated by 
address expression 


struction that 
caused trap 


address expression generates 


a reference to memory > 


80x1 
OOxy 


8040 


4 
Unrecognized op code 


5 
Scientific Branch 
instruction when SIP 
hardware not in 
system, or any other 
operation not 
Supported 


6 


Integer arithmetic 


overflow (with 
appropriate overflow 
trap enable bit of Ml 
register set to 1) 


7 
| Scientific divide 
by zero 


8 
Exponential overflow 


Instruction not recognized 
by CPU or SIP 


a reference to a register 


Undefined instruction whose 


address expression generates 
a reference to memory 


Overflow of target R-regis- 
ter during execution of 
instruction whose address 
expression generates a 
ceference to a register 


Overflow of target R-regis- 
ter during execution of 
instruction whose address 
expression generates a 
reference to memory 


A scientific divide (SDV) 
instruction has a divisor 
of zero 


A scientific operation 
produces an exponent greater 
than +63 


Undefined instruction whose 
address expression generates 


Same as for trap 5 


Instruction that 
caused trap 


First word of in- 
Struction that 
caused trap 


Instruction that 
caused trap 


First word of in- 
struction that 
caused trap 


Unspecified 


Unspecified 


Unspecified Unspecified’ 


Effective address 
of trap operand 


Unspecified 


Effective address 
generated by ad- 
dress expression 


Unspecified 


Effective address 
generated by 
address 


Pointer to scien- 
tific instruction 
that caused trap 


Pointer to scien- 
tific instruction 
that caused trap 


instruction 


instruction 


instruction 


instruction 


instruction 


Next CPU 
instruction 


Next CPU 
instruction 
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Table 7-1 (cont). 


Trap Number 
and Condition 


13 


Unprivileged use of 
privileged operation 


15 
Reference to 
unavailable resource 


HLT, RICN, RTCF, WDTN, or 
WDTF instruction 


LEV instruction whose ad- 
dress expression generates 
reference to a register 


LEV instruction whose ad- 


dress expression generates 
a reference to memory 


Input/output instruction 
whose first-word address 
expression generates a 
reference to a register 


Input/foutput instruction 
whose first-word address 
expression generates a 
reference to memory 


Instruction whose address 
expression generates a 
reference to (1) a memory 


address higher than the 
highest memory address 


Instruction that . 
caused trap 


Instruction that 
caused trap 


First word of 
instruction that 
caused trap 


First word of in- 
Struction that 


caused trap 


First word of 
instruction that 
caused trap 


First word of 
instruction that 
caused trap 


Contents of Selected Words of Trap Save 
Area When Trap Occurs 


Specific Event Saved Instruction Saved Z-Word Saved A-Word 


Unspecified 


Unspecified 


Effective address 
generated by ad- 
dress expression 


Unspecified 


Effective address 
generated by 
address 
expression 


Effective address 
generated by ad- 
dress expression 


Saved 
Program Counter 


Next location 


Next instruction 


Next instruction 


First word of 
instruction that 
caused trap, 
plus 2 


First word of 
instruction 
that caused 
trap, plus y 


Next instruction 


or (2) through indexing, a 
"wrap-around" memory address 


80d0 


a a, 
SN 


higher than 64K or less than 
0 


Input/output instruction 
that specifies an improper 
channel number; address 
expression generates a 
reference to a register 


Input/output instruction 
that specifies an improper 
channel number; address 
expression generates a 
reference to memory 


WDTN or WDTF instruction 
and watchdog timer not 
installed 


available but less than 64K 


First word of in- 
struction that 
caused trap 


First word of in- 
struction that 
caused trap 


0006 (WDTN); 0007 
(WDTF) 


Unspecified 


Effective address 
generated by ad- 
dress expression 


Unspecified 


First word of 
instruction that 
caused trap, 
plus y 


First word of 
instruction that 
caused trap, 


plus y 


Next location 
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Table 7-1 (cont). Contents of Selected Words of Trap 
Save Area When Trap Occurs 


Saved 
Specific Event Saved Instruction Saved Z-Word Saved A-Word Program Counter 


RTT instruction while TSAP Instruction that 80xl 
contains a null pointer caused trap 


Trap Number 
and Condition 


16 
Program logic error 


Unspecified Next instruction 


80x1 Unspecified Next instruction 


Instruction whose address Instruction that 


expression illegally gen- caused trap 
erates reference to a regis- 

ter (i.e., this instruction 

is not permitted to use a 

register address syllable) 


Bus parity error or un- Unspecified Unspecified Unspecified Unspecified 
recoverable memory data 

error 

An operation produces an Unspecified Unspecified 
exponent value of less 

than -64 while the asso- 

ciated enable bit in reg- 

ister M5 is set. 


20 A program error is detected Unspecified Unspecified 
Program error (SIP) by the SIP 


17 
Bus parity or memory 
error 


19 
Scientific underflow 


Pointer to scien- Next CPU 
tific instruction instruction 
that caused trap 


Pointer to scien- Next CPU 
tific instruction instruction 
that caused trap 


Pointer to scien- Next CPU 
tific instruction instruction 
that caused trap 


21 
Scientific signifi- 
cance error 


An integer is truncated Unspecified Unspecified 
during floating point to 

integer conversion while 

the associated enable bit 

in register M5 is set. 

The nonzero portion of a Unspecified Unspecified 
fraction is truncated 

while the associated enable 

bit of register M5 is set. 

The SIP or CIP attempts a Unspecified Unspecified 

write or read request bus tific instruction instruction 
cycle and receives a NAK that caused trap 

A read error occurs which Unspecified Unspecified Unspecified Unspecified 
the EDAC cannot correct, or 

the SIP or CIP detects a 

parity error. 

The divisor of a decimal Unspecified Unspecified Pointer to CIP Next CPU 
divide instruction (DDV) 

is equal to zero. . 


22 
Scientific precision 


Pointer to scien- Next CPU 
tific instruction instruction 
that caused trap 


23 
Nonexistent 
resource error 


Pointer to scien- Next CPU 


24 
Noncorrectable memory 
error or Megabus error 


25 
instruction that instruction 


CIP divide by zero 
caused trap 


OI-L 


800 


Table 7-1 (cont). Contents of Selected Words of Trap 
| Save Area When Trap Occurs 


and Condition Specific Event Saved Instruction Saved Z-word 


fw a ee ee 

; 264 Any of the following: Unspecified Unspecified 

CIP illegal 

specification o Undefined CIP op code 
detected. 


Program Counter 
SS a NTE 


Next CPU 
instruction 


Saved A-word 


Pointer to CIP 
instruction that 
caused trap 


One or both descriptors 
of an alphanumeric 
instruction is packed 
decimal. 


Decimal operand has a 
zero length. 


Operand in an Edit, VRF, 
or SRH instruction has 
a zero length. 


A separate signed decimal 
operand consists of only 
a sign (i.e., no digits). 


In a Move and Edit in- 
struction, the length of 
the receiving field was 
not exhausted, but either 
there are no micro-ops or 
the sending field length 
is exhausted. 


A second data descriptor . 
specifies an IMO, except 
for DCM and ACM 
instructions. 


The first data descriptor 
in a DSH specifies an 
IMO. 


A third data descriptor 
specifies an IMO. 


In an SRH instruction, 
the search length list is 
less than the search ar- 
‘gument list, or operand 
length less than operand 
element length. 


In a VRF instruction, 
verify list length is 
less than verify argument 
length, or operand length 
is less than operand ele- 
ment length. 


Table 7-1 (cont). Contents of Selected Words of Trap 
Save Area When Trap Occurs 


Trap Number Saved 
and Condition Specific Event Saved Instruction Saved Z-Word Saved A-Word Program Counter 
a 


278 
CIP illegal character 


Pointer to CIP 
instruction that 
caused trap 


Next CPU 
instruction 


Unspecified 


ee 


Next CPU 
instruction 


Pointer to CIP 
instruction that 
caused the trap 


CIP truncation error numeric instruction cannot 


contain all characters of 


the result. Whether or not: 


a trap occurs, the receiving 


field is altered to contain 
the leftmost part of the re- 


Any of the following: Unspecified 
o Illegal decimal digit 

detected (low-order four 

bits are not 0 through 

9). 

Illegal sign digit 

detected (not a recog- 

nized sign value). 

Illegal overpunch digit 

detected. 


Receiving field of an alpha- | Unspecified Unspecified 


sult and the CI (TR) is set. 
29° Any of the following: Unspecified Unspecified 


Pointer to CIP 
instruction that 
caused the trap 


Next CPU 
instruction 


ie a 2 


CIP overflow 
Receiving field of a 
decimal instruction 
cannot contain all signi- 
ficant digits of the 
result. 


During a Shift Lift in- 
Struction, a nonzero 
digit is shifted out. 


49 UW command Unspecified Unspecified Unspecified Unspecified 
Software trap 


a ‘ s A ‘ 5 7 
The Z-word format is described earlier in this section. 


>This is the address of the high-order (leftmost) end of a two-word operand. 


“If the watchdog timer is not present, this instruction causes a trap to vector 15 regardless 
of the privilege mode of the central processor. 


d ‘ . ‘ ; 
The Assembly Language Reference manual describes CIP trap handling in detail. 
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HONEYWELL-SUPPLIED TRAP HANDLERS 


The following software components provide trap handling 
facilities: Debug program, Commercial Simulator, and two ver- 
sions of the Floating-Point Simulator and the Scientific Branch 
Simulator - one for sSingle-precision and one for double-precision 
operations. The double-precision versions represent full hard- 
ware Simulation. The simulators are used when the hardware 
feature for scientific instruction processing is not installed. 
The Assembly Language Reference manual describes commercial and 
scientific instructions. 


Trap Handling by the Debug Program 


The Debug program operates as a unique task group identified 
by SD. It is loaded by use of the spawn group (SG) command which 
also specifies the terminal from which the debug directives are 
issued. (For a detailed description of the Debug program, see 
the Program Execution and Checkout manual.) Once the Debug pro- 
gram is loaded, you may set, clear, or print breakpoints in the 
task code by use of Debug directives. 


When the application program is executed, the Debug program 
is activated by trap number 2 which occurs each time a breakpoint 
is encountered. The action specified by the Debug directive (for 
that breakpoint) will then be executed. For example, designated 
memory locations may be printed out and execution of the applica- 
tion program continued without operator intervention. Alterna- 
tively, the Debug program may be placed in the interactive mode. 
In which case, you may use the Debug directives to display, 
change, and dump memory or registers. Information may be printed 
on a console or a line printer. 


Commercial Simulator 


The Commercial Simulator is the software component that 
Simulates the capabilities of the Honeywell Commercial Central 
Processor Model on other models that do not have native commer- 
cial instructions. 


The Commercial Simulator reacts to trap vector 5 (uninstall- 
ed instructions). It permits Intermediate COBOL, RPG, and as- 
sembly language programs to simulate the use of commercial 
instructions. 


The following programming considerations concern the 
Commercial Simulator: 


o The SIP/CIP arguments of the system building SYS direc- 
tive indicate existence of the Commercial Simulator. 
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o All other operation codes not handled by the Commercial 
Simulator are passed to the next trap handler for trap 
number 5. 


Floating-Point Simulator 


The Floating-Point Simulator reacts to trap number 3 
(scientific operation not in hardware). Trap number 3 (i.e., a 
trap to trap vector 3) occurs each time the central processor 
ee a scientific instruction during the processing of a 
task. 


While processing scientific instructions, the simulator 
provides automatic alignment of the operand's hexadecimal 
mantissas. It achieves maximum available precision by requiring 
that mantissas have no leading zeros (i.e., all mantissas must be 
normalized). 


Note the following programming considerations relative to 
the simulator: 


o The choice of the single-precision version (SSIP) or the 
double-precision version (DSIP) of the simulator is 
indicated in the SIP argument of the SYS directive for 
system building. | 


For SSIP only: 


o The simulator uses the R4 register, the R5 register, and 
the R7 register to simulate a scientific register. A 
task that includes scientific instructions should dedi- 
cate these three registers to the simulator's use. 


For SSIP and DSIP: 


o During its processing, the simulator may encounter an 
error condition specific to a scientific instruction: 
the following actions can occur: 


- The simulator will consult trap vector 5 if it en- 
counters (1) a Scientific instruction it does not Sup- 
port or (2) if a Supported scientific instruction 
generates a reference to a register other than the 
simulated scientific register or the R6 register. 


- The simulator will consult trap vector 7 if an SDV 
(Scientific Divide) instruction has a divisor of 0. 
The instruction will not be executed. 


- The simulator will consult trap vector 8 if execution 


of a scientific instruction produces exponential over- 
flow. The instruction will have been executed. 


Leaks CBO8 


- To use a software routine to react to any of these 
trap conditions, you muSt provide your own trap 
handler. The simulator will be invoked to handle traps 
caused by execution of scientific instructions only if 
the trap numbers have been enabled for the task execu- 
ting those instructions. 


o No "overflow trap enable" bit of the M register should 
set to l as the simulator begins operation. 


Scientific Branch Simulator 


The Scientific Branch Simulator reacts to traps to trap 
vector 5. It provides FORTRAN and assembly language programs 


with the means to simulate the use of the scientific branch 
instructions. 


Note the following programming considerations relative to 
the simulator: 


o The choice of the single-precision version (SSIP), or the 
double-precision (DSIP) of the simulator is indicated in 
the SIP argument of the system building SYS directive. 


For SSIP only: 


o The simulator uses registers R4, R5, and R7 as scientific 
accumulator (Sl) for comparisons; it uses Rl, R2, and R3 
as work registers. 


o The Simulator uses the G, L, and U bits of the I register 
to determine if the branch condition is true or false. 
When a normal return is made to the user program, the 
branch will be executed if the branch condition is true; 
otherwise, the next Sequential instruction following the 
one that was trapped will be executed. 


For both SSIP and DSIP: 
o All other operation codes not handled by the Floating- 
Point Simulator or the Scientific Branch Simulator are 


passed to the trap handler for trap 5. 


Software Generated Traps 


The following trap numbers (See Table 7-1) supports the task 
interrupt (break) function on KSR and TTY type devices. 


1 - User typed in a PI response following the **BREAK** 
prompter message. 
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48 - The user pressed the break or interrupt key on a KSR 
or TTY device while trap 48 was enabled. The user will 
receive a software trap as well as the opportunity to 
respond to the **BREAK** message. 


49 - User typed in a UW response following a **BREAK** 
prompter message. 


For a user program to receive one of these traps, it must 
have been enabled for the trap with the $TRPHD and SENTRP macro 
calls. The A- and Z-words in the TSA are meaningless; all other 
words are the same as for a hardware trap. 


USER-WRITTEN TRAP HANDLERS 
The system allows traps to be serviced in two ways: 


1. Trap handler connect (STRPHD) and enable user trap 
(SENTRP) macro calls. 


2. Trap handler directly attached to trap vector. 


The macro call approach requires that each task explicitly 
use the macro calls, and either include a uSer-Supplied trap 
handler in its bound unit (trap handler is part of task group 
dynamic memory pool) or reference an entry (linked with an EDEF 
directive) of a Monitor extension trap handler (trap handler is 
part of resident system). The user-supplied handler receives the 
TSA and register context exactly as if it was directly connected 
to the trap vector, but the Monitor has intercepted and analyzed 
the trap. 


The direct attachment approach requires a Monitor extension 
trap handler. This approach bypasses the Monitor overhead to 
analyze the trap, but requires the trap handler to be permanently 


memory resident and to be attached to the trap vector by user 
code. 


In either approach, the trap handlers must handle situations 
described below under "Trap Handlers DeSigned as Program Exten- 
sions" and "Programming Considerations for User-Written Trap 
Handlers." 


Trap Handlers Designed as Monitor Extensions 


It is assumed that all Honeywell and possibly some uSser- 
written trap handlers attached to the vector can encounter 
Situations which should be passed to the system default trap 
handler. Also, several handlers may process the same trap. To 
pass a trap in GCOS 6 from one handler attached to a trap vector 
to the next handler: 
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1. Load the trap handler, with an LDBU directive. The trap 
handler becomes a permanent part of the system and will 
allow privileged mode operation. The system, at system 
building, does implicit LDBU's for SIP/Commercial Simu- 
lator handlers if the hardware is not present, and SSIP 
and DSIP arguments were specified in a SYS directive. 


2. Write the handler to include initialization subroutine 
table (IST) code that will execute when the LDBU load 
operation occurs and save the current address contents 
of the trap vector(s) to be simulated, inserting its 
own pointer(s) instead. 


3. Code the user-written simulator to save the contents of 
all registers upon entry so that if the trap should be 
passed to the next trap handler, this handler can: 


a. Restore all saved registers. 


b. Execute a jump-indirect through the location con- 
taining the pointer of the next handler saved in 
step 2 above. The J-bit in the $Ml register must be 
off when the jump-indirect is executed. 


The rule is that each trap handler must get exactly the same 
information in registers and TSA that it would have received if 
it was the first trap handler accessed. 


Directly attached handlers are assumed to run in privileged 
mode. All handlers must contain IST code to insure that the trap 
vector pointer is to an odd location so that privileged mode is 
established. This is especially important when handlers are 
"chained" together on the same trap vector, Since privilege must 
be set for all trap handlers regardless of the order in which 
they are loaded. 


PROGRAMMING CONSIDERATIONS FOR USER-WRITTEN TRAP HANDLERS 


o Any trap described in Table 7-1 can occur if the as- 
sociated software- or hardware-related condition exists. 
As you are creating your application, you must consider 
which traps you wish to service with trap handlers. 


o A trap handler operates at the same priority level as the 


task whose execution caused the trap. The trap handler 
always executes in privileged mode. 
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When the trap handler has finished its work, the pri- 
vilege mode for "normal" task processing is restored as 
follows: A logical AND operation is performed using (1) 
the current setting of the P-bit of the S-register | 
and (2) the saved value of the privilege bit in the 
Z-word of the trap Save area. 


When a trap occurs, the hardware/firmware saves the task 
related contents of the I-register, the R3 register, and 
the B3 register in the trap save area. The trap handler 
is free to use these registers. 


see Table 7-1 for a description of the contents of Se- 


lected words in the trap save area when various traps 
occur. 


Upon entry to the user trap handler, the J-bit in the Ml 
register is arbitrarily turned off. Other bits in the 
Ml register remain as they were when the trap occurred. 
Register B3 contains a pointer to the A word in the TSA. 
Register R3 contains the vector number of the trap. 


Traps that occur within the user trap handler abort the 
task if they are the same type as the trap currently 
being processed. This is done to prevent all TSA's from 
being tied up due to recursive traps, and to prevent 
traps within the MCL interface from going to the user 
trap handler. 


Every trap handler should be reentrant; i.e., it should 
not use an internal work area to store interim informa- 
tion, Since this information could be lost if an inter- 
rupt occurs and, later, the same trap handler is called 
upon to execute at a different priority level. 


If you choose to define instructions of your own and have 
them interpreted by a trap handler connected to trap 
vector 5, you should limit the instructions to the user- 
reserved Subset of the generic instructions. The fol- 


lowing diagram illustrates the memory format of generic 
instructions. 
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BIT: Q / 8 15 


|0 0 0 00 0 00 0| f | 


f - Function; the user-reserved range of values 
for f is 128<f<256 (decimal). 


When a trap handler has finished its work, it must issue 
an RTT (Return From Trap) instruction. The J-bit in the 
Ml register is not restored. This instruction uses the 
current trap save area to restore the task-related con- 
tents of the I-register, the R3 register, the program 
counter, and the B3 register. Consequently, when the 
RTT instruction is executed, these elements of the trap 
Save area should be "correct" (i.e., as saved when the 
trap occurred). 


Note that in Some cases, particularly when a trap condi- 
tion is related to an input/output instruction, the 

Saved value of the program counter (in the trap Save 
area) will point to a memory location within the instruc- 
tion itself. This is not a legitimate point of return to 
"normal" task processing. In this case, the trap handler 
must modify the saved value of the program counter before 
issuing an RTT instruction. 


After the trap save area has been used to restore the 
registers indicated above, it is returned to the pool of 


available trap save areas pointed to by memory location 
0010,, . 


System wide user-written trap handlers may be loaded into 
the system area by including them, when the system is 
built, on LDBU directives. Alternatively, the trap 
handler may be linked and made a part of the same bound 
unit as the task code whose traps it will handle. These 
handlers use the SENTRP and STRPHD macro calls to 
associate the handler to the system. 


When a trap occurs, the contents of registers Ml through 
M7 are not saved in the TSA. Particular attention is. 
drawn to the Rl through R7 overflow trap enable bits of 
register Ml, which can be set by a privileged user. If 
the trap handler does not temporarily clear these bits 
during its execution, another user trap handler could be 
invoked erroneously on data register overflow. Such bits 
must be restored upon exit from the handler. 
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APPENDIX A 


DATA STRUCTURE FORMATS 


This appendix describes the data structures referred to in 
Sections 2, 3, and 4. The following structures are described: 


Clock request block (CRB) 

File information block (FIB) 

Input/output request block (IORB) 

Task request block (TRB) 

Parameter block 

Wait list 

semaphore request block (SRB) 

Message group request blocks (MGCRB, MGIRB, MGRRB) 


OO0O000 00 0 


Any of the structures can be hand coded. The CRB, FIB, SRB, 
and TRB can also be generated by macro calls or defined by macro 
call templates. The parameter block, input/output request block, 
wait list and message group request blocks, can be generated by 
macro calls. 


The first four items of the request blocks have an identical 
format (but slightly different contents, depending on the block 
type) as shown in Figure A-l. Later diagrams show the format of 
each block type; tables show the contents of the block entries. 


The data structures described here are as they appear for 
short address format (SAF) central processors, namely, one word 
items; the same structures for long address format (LAF) equip- 
ment would be 2-word entries for all pointers. | 


The first field (-SAF or -1) of a request block need be pre- 


sent only when the request block pointer/semaphore name is 
needed. 
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Figure A-l. First Four Items of Request Blocks 


CLOCK REQUEST BLOCK FORMAT 


Figure A-2 shows the format of the clock request block; 
Table A-1 shows its contents. 


0 1 2 3 4 5 6 7 8 9 A B C D E F 
REQUEST BLOCK POINTER/SEMAPHORE NAME | 


RESERVED-FOR SYSTEM USE 


womens Poffo [fol 
s : clofo|m}eo}e]olo | 


IF M=0, NEXT 3 WORDS ARE A DATE/TIME VALUE, 
OTHERWISE, NEXT 2 WORDS ARE AN INTERVAL 
IN UNITS SPECIFIED BY M.(SEE TABLE A-1.) 


—$AF) . 
eS lc _RRB/C_SEM 


0 
$AF C CT1 


1+$AF C_ CT2 


2+$AF Cc _T™ 


Figure A-2. Format of Clock Request Block 
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Table A-1. Contents of Clock Request Block 


3 a RENEE 


-SAF |C_RRB/| 0-15 
C SEM 


teal 


Depending on the condition or the S or R 
bits of C CTl, this word contains a request 
block pointer (R-bit on), or a Semaphore 

name (S-bit on). 


Reserved for system uSe. 


Return status 


This bit is set on while the request 
uSing this block is executing; it is 
reset when the request terminates. The 
system controls this bit; user Should not 
change it. 


Wait bit - set if the requesting task is 
not to be suspended pending the comple- 
tion of the request that uses this block. 


User bit. User may or may not use this 
bit; the system does not change it. 


Release semaphore indicator. Values: 
O=No release, 1=Release, on timeout, of 
item named in C_RRB. 


Must be zero. 


Return request block indicator. Values: 
O=No dispatch, 1=Dispatch of request 
block named in C_RRB, after timeout of 
this request. 


Delete clock request block. Values: 

O=No delete, 1=Return memory to the pool 
where CRB is the first entry of its mem- 
ory block. 


I/O bit. Must be set in absence of Start 
address. 


Value is -l. 


When set, indicates this block is associ- 
ated with a cyclic clock function. 


1+SAF|C cT2 
8 (C) 
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Table A-1 (cont). Contents of Clock Request Block 


pit(s) __Contents 


1+SAF | C_CT2 i) |] When set, last two words contain an in- 

(cont) (cont) terval in units specified by M. Each in- 
terval value is as follows: C01 - in 
milliseconds; 010 - in tenths of a sec- 
ond; O11 -—- in Seconds; 100 - in minutes; 
101 - in units of clock resolution. 


When reset (off), the last three words 
contain a date/time interval. 


FILE INFORMATION BLOCK FORMAT 


Figure A-3 shows the format of the file information block; 
Table A-2 shows its contents. 


INPUT KEY POINTER 


F_IKF/FLIKL INPUT KEY FORMAT/INPUT KEY LENGTH 


0 F_LFN | LOGICAL FILE NUMBER 

1 F_PROV PROGRAM VIEW 

—— 
4 FLIRL/F_BFS2 
5 - FLORL/F_BKSZ 
6  F_LIRT/F_BKNOT 
) ELHIRTIF_eKNOZ 
8 FORT 
pr 
10 

1 INPUT KEY FORMAT/INPUT KEY LENGTH 
12 FLORAI 
14 F_RFU . 
; 


Figure A-3. Format of File Information Block (FIB) 
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{ Table A-2. Contents of File Information Block (FIB) 


EE Ie I I EE ELE OE RD ND Oe ee ee ER oe IEEE, a SEES 
0 


-15 Logical file number (LFN) 


Access level - set on for storage manage- 
ment, off for data management. 


Process rules — bit 1 for SRDREC/SRDBLK, 
bit 2 for SWRREC/SWRBLK, bit 3 for SRWREC, 
bit 4 for SDLREC. 


Key type - bit 5 for primary keys, bit 8 
for relative keys, bit 9 for simple keys 
(bits 6 and 7 must be QO). 


Record class - set on for fixed-length re- 
cords only, off for fixed- and variable- 
length records. 


Record visibility - set on if deleted re- 
cords are to be visible, off if invisible. 


Key storage alignment - set on if storage 
area begins at odd-byte boundary, off if 
even-byte boundary. 


Record storage area/buffer alignment - set 
on if record storage area (or buffer) be- 
gins on odd-byte boundary, off if even- 
byte boundary. 


Transcription mode - set on if data trans- 
ferred in binary transcription mode, off 
if ASCII mode. 


Synchronous/asynchronous indicator - set 
on if SRDBLK/SWRBLK calls executed asyn- 
Chronously, off if executed synchronously. 


Start address of user record area (data 
management) or Start address of buffer 
area (storage management). 


Input record length (data management) or 
transfer size (storage management). 


Output record length (data management) or 
block size (storage management). 
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Table A-2 (cont). Contents of File Information Block (FIB) 


F LIRT/ 0-15 Must be 0000 for data management; is the 
F _BKNO left half of the block number (F _BKNO1) 
F HIRT/ 
F _BKNO2 
Must be 0000. 
ma Start address of user key area. 


for Storage management. 

Input key format (0 for none specified, 
1 for primary key, 2 for Simple key) 
Input key length. 


Must be FFFF for data management; is right 
half of the block number for storage 
management. 


Output record address (left half). 
Output record address (right half). 


Reserved for future use. 


INPUT/OUTPUT REQUEST BLOCK FORMAT 


Figure A-4 shows the format of the input/output request 
block; Table A-3 shows its contents; Table A-4 summarizes the 
IORB fields for the operator interface functions. 
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B C D E F 


0 1 2 3 4 5 6 7 & 9 A 
REQUEST BLOCK POINTER/SEMAPHORE NAME 
RESERVED FOR SYSTEM USE AS A POINTER 


—$ 
oe 
) 


bi) RRB/I_SEM 


ie | aa nen eiwiuielelalele! 
ee Oe 


Figure A-4. Format of I/O Request Block 


Table A-3. Contents of I/O Request Block 


Label Bit(s) Contents 
aa ee 


I_ RRB/{0-15 Depending on the condition or the S or 
for SAF;}R bits of I CTl, this word contains a 
request block pointer (R-bit on), or a 
0-31 semaphore name (S-bit on). Set by 
for LAF user; used by system at termination 
of request. 


Reserved for system use. 1- or 2-word 


pointer to indirect request block. 


Return status 


This bit is set (on) while the request 
uSing this block is executing; it is 
reset when the request terminates. The 
system controls this bit; user should 
not change it. 
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Table A-3 (cont). Contents of I/O Request Block 


Bit(s) 


SAF I. CTl Wait bit - set if the requesting task 
(cont) (cont) is not to be suspended pending the com- 
Pletion of the request that uses this 
| block. | 
| User bit. User may or may not use this 
bit; the system does not change it. 
Release semaphore indicator. Values: 
O=No release, 1=Release, on timeout, 
of item named in I_ RRB. | 
Must be zero. | 
Return request block indicator. 
| Values: O=No dispatch, 1=Dispatch of 
| request block named in I RRB, after 
timeout of this request. (System 
executes SROTSK, using I_RRB, upon 
task termination). 
| Delete I/O request block. Values: 
O=No delete, 1=Return memory to the 
pool where IORB is the first entry of 
its memory block. 
I/O bit. Must be set. 
1+SAF LiCT2 Logical resource number (LRNO; identi- 
fies device to be used. 
IBM-type request. Changes interpreta- 
tion of I_ DVS to task word, and of 
I_RSR and I ST to configuration words 
A and B respectively. 
Byte Index: O=buffer begins in left- 
| most byte of word, l=buffer begins in 
rightmost byte. 
Private space; reserved for system use. 
O=Standard IORB; 1=IORB is extended to 
ao at least 6+2*SAF items. 
Function code. Driver or LPH function, 
see Table 6-1. 
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aie, 
A 


Table A-3 (cont). Contents of I/O Request Block 


2+SAF TT ADR _ADR Buffer address, SAF. 
Buffer address, LAF 1- or 2-word 
2+2* SAF | I _RNG 


pointer. 
3+2*SAF | I _DVS 


SER 
_ a 


Table A-4. core of IORB Fields for Operator Interface 


san For a SOPMSG call, the setting of the 
W-bit in the output IORB controls re- 
1+SAF I CT 2 
9 (B) 


Range —- number of bytes to be 
transferred. Used as input field for 
cartridge disk or disk storage unit. 


Device-specific information. 


Residual range. Indicates the number 
of bytes not transferred. Filled in by 
the system on completion of the order. 
Used by the cartridge disk and mass 
Storage unit drivers as a data offset 
value. 


Status word. Reflects the mapping of 
the hardware status into software 
Status format; used as input field 
high-order bits of sector number for 
mass storage unit. 


turn to the caller. For a SOPRSP call, 
the setting of the W-bit in the input 
IORB controls return to the caller; the 
setting of the W-bit in the output IORB 
has no Significance. For either call, 
return to the caller is immediate if 
the significant W-bit is on. If the 
Significant W-bit is off, return to the 
caller occurs after the order is 
completed. 


LRN=0 


Must be off if the input/output buffer 
begins at the left byte of the word 
whose address is contained in word 3 
(I ADR) of this IORB. Must be on if 
the input/output buffer begins at the 
right byte. 
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Table A-4 (cont). Summary of IORB Fields 
for Operator Interface 


| ttem Label Bit(s) Contents 


The word address of the message buffer 
(which contains an output message or 
is to receive an input meSsage). 


2+2*SAF | I RNG 0-15 The buffer size in bytes. This is the 
| length of an output message or the 


maximum length allowed for an input 
message. 


SEMAPHORE REQUEST BLOCK FORMAT 


Figure A-5 shows the format of the semaphore request 
block; Table A-5 shows its contents. 


—$AF 
\_ ts RRB/S_SEM REQUEST BLOCK POINTER/SEMAPHORE NAME 
0 RESERVED FOR SYSTEM USE 


meee Tc Cd 
vue [fo fe foto fob toto 
2+$AF S_ADR SEMAPHORE IDENTIFIER | 


Figure A-5. Format of Semaphore Request Block 


Table A-5. Contents of Semaphore Request Block 


S RRB 


Depending on the condition of the S or 
R bits of S CTl, this word contains a 

request block pointer (R-bit on), or a 
semaphore name (S-bit on). 


S SEM 


Return status 


This bit is set (on) while the request 
uSing the block is executing; it is re- 
set when the request terminates. The 
system controls this bit; user should 
not change it. 
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Table A-5 (cont). Contents of Semaphore Request Block 


Wait bit - set if the requesting task 
is not to be suspended pending the 
completion of the request that uses 
this block. 
User bit. User may or may not use this 
bit; the system does not change it. 
Release semaphore indicator. Values: 
O=No release, l1=Release, on timeout, 
of item named in S_RRB. 
Must be zero. 
Return request block indicator. 
Values: O=No dispatch, 1=Dispatch of 
request block named in S RRB, after 
timeout of this request. 
Delete semaphore: request block. | 
_— Values: O=No delete; 1=Return memory 
F to the pool where SRB is the first 
% entry of its memory block. 
I/O bit. Must be set in absence of 
start address. 


1+SAF So CT2 Value is -l. 
Must be Zero. 
Must be one. 
Semaphore identifier - two ASCII 
| characters. 


TASK REQUEST BLOCK FORMAT 


Figure A-6 shows the format of the task request block; 
Table A-6 shows its contents. 
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oe 
—1 —e 
0 RESERVED FOR SYSTEM USE AS A POINTER 


vag womans [tw] oe [o[afole 
worn [mie fe fo foe Pole 


2+$AF T_ADR START ADDRESS IF 1!=0 


\T_RRB/T_SEM REQUEST BLOCK POINTER/SEMAPHORE NAME 


2+2*$AF T_PRM BEGINNING OF ARGUMENT LIST 


Figure A-6. Format of Task Request Block 


Table A-6. Contents of Task Request Block 


| Item Bit(s) Contents 


TARR (AINE URNA, Er ER MINOT RACAL NE CASA IUENINES SIC IINIT 10 ERIC LIE TRIG RW INE PORESRNGD OSS Se fain Bec OR NEED WN i IN Se gl I OE ST ER OO ie eI NID 
—-SAF T RRB/| 0-15 Depending on the condition of the S or 
-]l T SEM R bits of T CTl, this word contains a 

request block pointer (R-bit on), or a 
semaphore name (S-bit on). 
O-7 Return status 


SAF T CTl 


8 (T) This bit is set (on) while the request 
uSing this block is executing; it is 
reset when the request terminates. The 
system controls this bit; the user 
Should not change it. 


Wait bit - set if the requesting task 
is not to be suspended pending the com- 
pletion of the request that uses this 
block. 


User bit. User may or may not use this 


bit; the system does not change it. 


Release semaphore indicator. Values: 
O=No release, 1=Release on timeout of 
item named in T_RRB. 


Must be zero. 
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Table A-6 (cont). Contents of Task Request Block 


Bit(s) Contents 
RE A eR a cL RY Ce eed EET dE TS 
D(R) Return request block indicator. 
Values: O=No dispatch, 1=Dispatch of 
request block named in T RRB, after 

timeout of this request. 


Delete task request block. Values: 0O= 
No delete; 1=Return memory to the pool 
where TRB is the first entry of its 

memory block. 


I bit. 
address. 


Must be set in absence of Start 


Logical resource number (LRN). 


Must be zero. 


Start address if the I-bit of T _CT1 is 
reset (zero), 
Beginning of argument list. 


Figure A-7 shows the format of the parameter block. 


8-15 


PARAMETER BLOCK FORMAT 
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NUMBER OF PARAMETERS 
az ADDRESS OF PARAMETER 14 


NUMBER OF BYTES 


ASCI! CHARACTER | ASCI!| CHARACTER 


ASCII] CHARACTER | A 


| NUMBER OF BYTES 


ASCII CHARACTER | ASCII CHARACTER 


ra | UNSPECIFIED 


NOTE: The parameter value strings need not be contiguous 
with the address portion of the paramter block; 
if the block is system generated, each paramter will 
have a trailing blank that is not included in the 
byte count. 


Figure A-7. Format of Parameter Block 
WAIT LIST FORMAT 


Figure A-8 Shows the format of the wait list. 


NUMBER/ITEMS TO WAIT FOR TOTAL ITEMS IN LIST 
ADDRESS OF FIRST REQUEST BLOCK ’ 


ADDRESS OF EIGHTH REQUEST BLOCK 


Figure A-8. Format of Wait List oe 
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MESSAGE FACILITY MESSAGE GROUP REQUEST BLOCKS 


Tables A-7, A-8, and A-9 respectively show the content of 
the following message facility message group request blocks: 


o Message group control request block (MGCRB) 
o Message group initialization request block (MGIRB) 
Oo Message group recovery request block (MGRRB) 


Templates for these request blocks are generated by the 
SMGCRT, SMGIRT, and SMGRRT macro calls respectively. 


The request blocks can be generated by the SMGCRB, SMGIRB, 
and SMGRRB macro calls respectively. 


Table A-7. Message Group Control Request Block (MGCRB) 


MC_OS Address Pointer 


O-15 (SAF)}] Reserved for system use. 
O-31 (LAF) | Reserved for system use. 
SAF MC MAJ Major status. 


Left byte: reserved for system 
use. 


Right byte: This byte is set (on) 
while the request using this block 
is executing; it is reset when the 
request terminates. The system 
controls this bit; user should not 
change it. 


Wait bit - set if the requesting 
task 1s not to be suspended pending 
the completion of the request that 
uses this block. 


User bit. User may or may not use 
this bit; the system does not 
change it. 


Release semaphore indicator. 
Values: Q=No release, l1=Release, 
on timeout, of item named in I RRB. 
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Table A-7 (cont). Message Group Control Request Block (MGCRB) 


SAF MC MAJ C Must be zero. 
(cont) (cont) 
D (R) 
EF (D) 
1+SAP MC_OPT 


2+SAF MC_BIF 
Buffer pointer. 


3+2*SAF | MC DVS a Record-type code. 


Return request block indicator. 
Values: O=No dispath, 1=Dispatch 
of request block named in I RRB, 
after timeout of this request. 
System executes SROTSK, using I RRB 
upon task termination. | a 


Delete I/O request block. Values: 
O=No delete, 1=Return memory to the 
pool where IORB is the first entry 
of its memory block. 


hy 


I/O bit. Must be set. 
General options: 


Reserved for system use. 


Must 


Byte index: 0 = Buffer begins in 
leftmost byte of the 
word. 


1 = Buffer begins in 
rightmost byte. 


be 0. 


be 1 (extended IORB). 


Address Pointer 


O-15 (SAF) | Buffer pointer. 


0-31 (LAF) 
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Table A-7 (cont). Message Group Control Request Block (MGCRB) 


Item Bit(s) Contents 


MC_ REC | 0-F On send, insert record-type code. 


On receive, return asSigned record- 
type code. 


4+2* SAF MC_RSR | 0-F Residual range. 


5+2 *SAF MC_MRU | 0-7 Left byte: end message recovery 
unit (MRU). Reserved for system 
use. 


MC_WTI | 8-F Right byte: wait test indicator. 
00 Return null value 
to application. 
O1 = Wait 
6+2* SAF MC_ EXT Extension mechanism. 
0-7 | Left byte: binary value of 
= 13+2*SAF, i.e., number of words in 
% IORB following the extension word. 
Right byte: must be hexadecimal 7. 


7+2* SAF Next seven words. Reserved for system physical I/O use. 


14+2*SAF | MC_FNC | 0-7 Left byte: function. Reserved for 


system use. 


8—F Right byte: revision. Must be 
hexadecimal 1. 


15+2*SAF | MC MGI Message group i.d. 


O-F Returned in the SMINIT and SMACPT 
macro calls. 


16+2*SAF | MC_LVL Enclosure level. 
O=7 Left byte: enclosure level 
requested. 
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Table A-7 (cont). Message Group Control Request Block (MGCRB) 


End of quarantine unit 


16+2*SAF | MC LVL | 8-F Right byte: enclosure level de- 
(cont) (cont) 
End of message. 


tected according to following ASCII 


values: 
18+2*SAF | MC VDP] Address Name-list pointer. 
O-15 (SAF)] Must be 0. 
O-31 (LAF) Must be 0O. 


18+3*SAF MC_TGI Reserved for system use. 


19+3*SAF| MC TSK | Address Pointer. 
O-15 (SAF)| Reserved for system uSe. 
O-31 (LAF)| Reserved for system use. | | 
1944*SaF | C_NPI ust be 0. 


Table A-8. Message Group Initialization Request Block (MGIRB) 


Not end of record 
End of record 


1 NO KF © 


Bit(s) | Contents 


Address | Pointer: reserved for system use. 


0-15 (SAF) 
0-31 (LAF) 


Major status. 


Left byte: reserved for system 
use. 


Right byte: This bit is set (on) 
while the request using this block 
is executing; it is reset when the 
request terminates. The system 
controls this bit; user should not 
change it. 
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f Table A-8 (cont). Message Group Initialization 
Request Block (MGIRB) 


Wait bit - set if the requesting 
task is not to be suspended pending 
the completion of the request that 
uses this block. 


User bit. User may or may not use 
this bit; the system does not 
change it. 


Release semaphore indicator. 
Values: 0O=No release, 1=Release, 
on timeout, of item named in I_RRB. 


Must be zero. 


Return request block indicator. 
Values: O=No dispatch, 1=Dispatch 
of request block named in I_RRB, 
after timeout of this request. 
(System executes SROTSK, uSing 

I_ RRB, on task termination.) 


Delete I/O request block. Values: 

O=No delete, 1=Return memory to the 
pool where IORB is the first entry 

of its memory block. 


I/O bit. Must be set. 


General options. 


0-7 Reserved for system use. 
8—-A Must be 0. 

B Must be 1 (extended IORB). 
C-F Must be 0. 


Address Pointer. 
0-15 (SAF) Must be 0. 
O-31 (LAF)! Must be 0. 


Must be hexadecimal l. 


2+SAF MI_BUF 
2+2* SAF MI BSZ Buffer range. 
O-F Must be 0. 
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Item 


MI_RSR 


4+2*SAF 


5+2*SAF 


6+2*SAF 


7+2*SAF 


14+2* SAF 


15+2* SAF 


16+2* SAF 


18+2*SAF 


Table A-8 (cont). 


Label 


MI EXT 


Bit(s) 


Message Group Initialization 
Request Block (MGIRB) 


Residual range. 
Reserved for system use. 


Left byte: must be 0. 
Right byte: must be OQ. 


Extension mechanism. 


Left byte: binary value of 
314+2*SAF, i.e., number of words in 
IORB following the extension word. 


Right byte: must be hexadecimal 7. 


Next seven words. Reserved for system physical I/0 uSe. 


19+2*SAF | MI NWI 


20+2*SAF 


MI NDI | 


Function. 


Left byte: reserved for system 
use. 


Revision. 
Right byte: must be hexadecimal l. 
Message group i.d. 


Returned in the SMINIT and SMACPT 


macro calls. 


Address type. 


Left byte: address type 
(initiator); must be hexadecimal l. 


Right byte: address type 
(acceptor); must be hexadecimal l. 
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Table A-8 (cont). Message Group Initialization 
Request Block (MGIRB) 


Item Label  Bit(s) Contents 


21+2*SAF | MI_ MBI Initiator mailbox name. 


Must be from 1 to 12 ASCII 
characters, blank-filled, left 
justified. 


O-F 
27+2*SAF | MI_NWA Must be 0. 


29+2*SAF | MI_MBA Acceptor mailbox name. 


Must be from 1 to 12 ASCII charac- 
ters, blank-filled, left justified. 


0-F 
O-F Initiator - maximum size of quaran- 
tine unit. 
6+2*SAF | MI CNT | 0O-F Count of number of active messages 
in the mailbox. Returned with 
SMCMG macro call. 


FF 


37+2*SAF | MI TGI Reserved for system use. 
38+2*SAF | MI TSK Pointer. Reserved for system uSe. 


| 38+3*SAF | MI SIP Reserved for system use. 
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Table A-9, 


Address 


0-15 
0-31 


(SAF) 
(LAF) 


Message Group Recovery Request Block (MGRRB) 


Pointer. 
Reserved for system use. 
Reserved for system uSe. 


Major status. 


Left byte: reserved for system 


use. 


Right byte: This bit is set (on) 


while the request using this block 


is executing; it is reset when the 
request terminates. The system 
controls this bit; user Should not 
change it. 7 


Wait bit - set if the requesting 
task is not to be suspended pending 
the completion of the request that 
uses this block. 


User bit. User may or may not use 
this bit; the system does not 
change it. 


Release semaphore indicator. 
Values: O=No release, 1=Release, 
on timeout, of item named in I_ RRB. 


Must be zero. 


Return request block indicator. 
Values: O=No dispatch, 1=Dispatch 
of request block request. (System 
executes SROTSK, using I RRB, upon 
task termination.) — 


Delete I/O request block. Values: 

O=No delete, 1=Return memory to the 
pool where IORB is the first entry 

of its memory block. 


I/O bit. Must be set. 
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Table A-9 (cont). Message Group Recovery 
Reguest Block (MGRRB) 


Label Bit(s) Contents 


Item 


1+SAF MR OPT 
0-7 
8-A 
B 
C-F 


2+SAF MR BUF | Address 
O-15 (SAF) 
O-31 (LAF) 


General options. 


Left byte: reserved for system 
use. 


Right byte: 
Must be 0. 
Must be 1 (extended IORB). 


Must be 0. 


Pointer. 
Must be 0. 
Must be 0. 


Buffer range. 
O-F Must be 0. 
MR ITP Must be 0. 
“a 
Q-7 


2+2*SAF | MR_BSZ 


34+2* SAF 


4+2*SAF MR_RES Residual range. 
Reserved for system use. 


5+2*SAF MR_RSN Reason-for-terminate code: 


Normal message group 
termination. 


34-44 = User-defined abnormal 
termination of message 


group. 


Reserved for system use. 
6+2*SAF MR_EXT Extension mechanism. 


0-7 Left byte: binary value of 
144+2*SAF, i.e., number of words 


in IORB following the extension 
word. 


8—-F Right byte: must be hexadecimal 7. 


7+2*SAF Next seven words. Reserved for system physical I/O use. 
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Table A-9 (cont). Message Group Recovery 
Request Block (MGRRB) 


Bit (s) contents 
BENE CEE 


14+2*SAF | MR_FNC Left byte: function. 
0-7 Reserved for system use. 
MR_REV Right byte: revision. 
8-F Must be hexadecimal Ol. 
15+2*SAF | MR_MGI Message group i.d. 
O-F Returned in the SMINIT and SMACPT 
macro calls. 
O-F 


16+2*SAF | MR CNC sor Reserved for system use. 


17+2*SAF | MR_FMT | Address Pointer. 
| 0-15 (SAF) | Must be 0. 
0-31 (LAF) | Must be 0. 


18+3*SAF | MR_MRU | 
(Two Reserved system 
words) Reserved system 


19+3*SAF} MR_AMU 
(Two Reserved system 
words) Reserved system 
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APPENDIX B 


WRITING A PERIPHERAL I/O DRIVER 


To add a new function to a Honeywell-supplied driver, the 
user must modify its existing source code, then relink the system 
with the new driver (see Section 6). 


To operate with a device that is not supported, the user 
must write hisS own driver. This appendix describes what the uSer 
must be aware of in writing a driver. 


SYSTEM BUILDING CONSIDERATIONS IN WRITING A DRIVER 


The system building process defines the driver and those 
data structures necessary for the driver to interface with the 
user and with the system. The driver can reference only two data 
Structures, input/output request blocks (IORBs), and resource 
control tables (RCTs). 


An RCT is generated by the DRIVER directive in system build- 
ing (see "Driver Directive" in the GCOS 6 MOD 400 System Building 
manual). The RCT must be at lease three words, in both short 
address form (SAF) and long address form (LAF). Requirements for 
Stack space are 22 words in SAF, and 40 words in LAF. RCT and 
stack sizes are specified by the left and right bytes, respec- 
tively, in the RCT size argument of the system building DRIVER 
directive. The flags word R FLGS in the RCT must be set up dur- 
ing driver intialization. — 


The user must link the driver aS a Separate bound unit. Any 
references to any system function routine (described under 
"Driver Usable System Functions" below), must be specified in an 
EDEF directive to the Linker. 

Example: 


The following system building DRIVER directive generates a five- 
word RCT with 22 words of stack space: 


DRIVER ‘“VOL1>OWNDRIVER, 4,9,X'1380',X'1605! 
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The user-written driver OWNDRIVER will be loaded from the volume 
major directory on volume VOL1. A task control block (TCB) is 
generated and will be fixed to level 9. A pointer in the LRN 4 
position of the logical resource table (LRT) will be set up to 
point to the generated RCT. The device channel X'1380' will be 
set up in the first word of RCT. 


DRIVER INTERFACE IN WRITING A DRIVER 


The user interfaces with the driver by placing task requests 
against the driver via the S$RQIO macro. The system uses an LRN- 
to-RCT-to-TCB (priority level) association to associate a request 
with a specified driver. When the driver is turned on to service 
a request, S$B4 will point to the IORB to be serviced. Since de- 
vices may interrupt to a specified level when an attention oc- 
curs, the user-written driver should first check SB4 for null to 
ascertain if a request or attention is being processed. 


Drivers should not alter the first six entries of an IORB. 
IORB's should be generated as described in Section 6. 


Drivers must terminate with an internal terminate as des- 
cribed under "Driver Usable System Functions." 


USER-WRITTEN DRIVER INITIALIZATION 


On entry to the driver for the first request, the driver 
must locate the resource control table for the device, using the 
LRN in the input/output request block (IORB). The driver must 
set register SB7 to point to a stack area, and must store in the 
Stack a pointer to the RCT. Thus, when an attention occurs, the 
driver may locate the RCT by retrieving the RCT pointer from the 
Stack. The following instructions sequence locates the RCT and 
sets the stack pointer: 


LLH $R2,$B4,I CT2 GET LRN FROM IORB 
LNJI $B5,<<{ZXSRCT LOCATE RCT 

LAB $B7,$B2.-SAF SET STACK POINTER 
STB $B2,-SB7 SAVE POINTER TO RCT 


Driver initialization must also set up the. flags word R _FLGS 
in the RCT to reflect the characteristics of the device (see 
Section 6), 3 


Finally, the driver must set the device interrupt level, and 
read the device status. These functions may be accomplished by 
calling one of the subroutines described under "Driver Usable 
System Functions" below. 
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The driver may also set up the device type (R_TYP) during 
initialization, with the I/O instruction with a function code 


"input device ID" (see the Honeywell Level 6 Minicomputer 
Handbook). 


DRIVER USABLE SYSTEM FUNCTIONS 


To provide compatibility with the system, user-written 
drivers may call only the following system functions, using the 
format and register contents as shown for each function: 


I/O subroutines (ZIOSUB) 

Locate RCT for a device (ZXSRCT) 
Terminate driver (ZXD TR) 

Output address and range (ZIOLD) 


O00 0 


I/O Subroutines (ZIOSUB) For User-Written Drivers 


The common driver subroutines are called by executing the 


instruction: LNJ $B5,<ZIOSUB with standard register contents 
as follows: 


Function code in SRl 
RCT address in SB6 
Current stack position in SB7 


INITIALIZE FUNCTION (Code 0) 


The initialize subroutine intializes the device interrupt 
level, removes the level from the first word of the RCT, and 
exits with the device status in R._STTS of the RCT. 


Input registers: Standard registers for I/O subroutines 


Return registers: 


o  SR1l = Return status 


O = Normal 
A = Controller unavailable 
o SR4 = Channel number 


o S$R2, SR6 altered 
WAIT ON LINE FUNCTION (Code 1) 


If the attention flag in the RCT is 0, wait for the next 
online interrupt, or until five minutes have elapsed. 


If the attention flag is 1, return with successful comple- 


tion status if the device is ready; otherwise wait for the next 
online interrupt or until five minutes have elasped. 
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Input registers: 


o Standard registers for I/O subroutines 
o SR4 = Channel number 


Return registers: 


o SR1 = Return status 


QO = Normal 
6 = Five minutes elapsed; not yet online 
-l1 = Status of device could not be read following 


interrupt. 
A = Controller not available. 
o SR5, SR6, SR7 altered 
STOP I/O FUNCTION (Code 2) 


Issue "Stop I/O" order to the device whose channel number is 
in the $R4 register; call the Wait for Interrupt function. 


Input registers: Same as Wait on Line function above. 
Return registers: 


o SR1 = Return status 


O = Normal 
6 = Time-out 
-l = Negative acknowledgement to status request 


o SR5 = Modified status. Bits 0, 1, and 12 cleared to 0; 
bits 13 through 15 cleared and logical OR performed 
with the result placed into bit 15 branes error 
bit). 

o SR6 = Status (Same as R_STTS in the RCT) 

o SR7 = Residual range 


WAIT FOR INTERRUPT (Code 3) 


Activate timer to time the number of seconds specified in 
SR6; call the Read/Modify Status function. 
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Input registers: 


o Standard registers for I/O subroutines 


Oo 6SR4 
o SR6 
Return 
o §6SRI 
fe) 6 
o @6©SR5 
o 6 SR6 
o SR7 
READ/MODIFY 


= Channel number 
= Timer value, in seconds 


registers: 


Return status 


= Timeout (Same as Read/Modify Status if no time-out) 


= Modified status. Bits 0, 1, and 12 cleared to 0; 
bits 13 through 15 are cleared and logical OR per- 
formed with result placec into bit 15 (fatal error 
bit). 


= Status (Same as R STTS in the RCT) 


Residual range 


STATUS FUNCTION (Code 4) 


Input registers: 


o Standard registers for I/O subroutines 


Return 
o §6SR1 

-l 
Oo SR5 


= Channel number 


registers: 


= Return status 


Status request received negative acknowledgement 


= Modified status. Bits 12 through 15 cleared to 0 
and logical OR performed with result placed into 
bit 15 (fatal error bit). 


Locate RCT for Device (ZXSRCT) 


This system function, to locate an RCT for a specific de- 
vice is called with the instruction: LNJ SB5,<ZXSRCT, with S$R2 
containing the LRN for the device. 


Input registers: 


o SR2 


= LRN value 
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Return registers: 


re) SR1 = Return status 
O = RCT found for LRN 
0802 = Illegal LRN 
O SB2 = Pointer to RCT 
O SR2 = altered 


Driver Terminate (ZXD_TR) 


The system function to terminate a driver is called with the 
instruction: LNJ S$B5<ZxXD_TR. 


Input registers: 


o SR2 = Return status for current request 
o SB4 = Start address for next execution of driver 
o S$B7 = Current stack position. 


The system function to output the address and range for a 
data transfer is called with the instruction: LNJ SB5<ZIOLD. 
The ZIOLD subroutine adjusts any necessary change of address 
Space and also performs the IOLD order. 


Input registers: 


o $B3 = Buffer address 

o SR2 = Buffer byte offset 
o S$R3 = Range 

o S$R4 = Channel number. 


No registers are altered by ZIOLD. 
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SET UP STACK 
POINTER IN $B7; 
SAVE RCT POINTER 
IN STACK. 


INITIALIZE R_FLGS 
IN RCT; READ DEVICE 
id INTO R_TYP. 


GET LRN FROM IORB; 
LOCATE RCT WITH 
LNJ$B5, - ZXSRCT 


EXTERNAL 
ENTRY 


INITIALIZE 
Z10SUB 
FC =0 


SET $R2 =STATUS, 
$B4 = START 
ADDRESS. 


TERMINATE 
ZXD_TR 


DEVICE 
SPECIFIC 
INITIALIZATION 


READY/MODIFY 
STATUS 
Z10SUB FC =4 


NORMAL 
START 


SET $R2 = STATUS, 
$B4 = START 

ADDRESS. TERMINATE 
VIA ZXD_TR. 


RESTORE RCT 
POINTER 
FROM STACK 


STATUS STOP 1/0 GOOD SET CONTROLLER 
OBTAINED ZIOSUB COMPLETION UNAVAILABLE 
? FC=2 ? STATUS 


DOES 

FUNCTION 

IMPLY IGNORE 

DISABLED 
? 


WAIT ONLINE 
ZIOSUB FC = 1 


DEVICE 


DISABLED 
? 


SET DISABLED 
STATUS 


DEWICE SET NOT 


REARS READY STATUS 


YES : NO 


PREPARE DEVICE 10 YES TIMED WAIT 
FOR TRANSFER ACCEPTED Z10SUB 
START 1/0 ? » FC=3 


Figure B-l. Typical Device Driver 
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“STATUS \_ NO STOP 1/0 GOOD wa 
OBTAINED Z1OSUB COMPLETION 

, FC=2 ? 
“Le Ny 


DEVICE 
READY 


SET TIME OUT 
STATUS 


SET DEVICE NOT 
READY STATUS 


DOES 
DRIVER 
RETRY 


SET HARDWARE 
ERROR STATUS 


YES 
a es NO _ /ATRANSFER NNO BET aS YES 
D cer ere EXHAUSTED 
: a, : 3 
YES YES NO 


UPDATE RETRY 


DEVICE 
SPECIFIC 


COUNT 


COMPLETION 


SET NO 
ERROR 


Figure B-1l (cont). Typical Device Driver 


GENERAL I/0 REQUIREMENTS FOR USER DEVICE DRIVER 


This subsection describes in general terms how to initiate 
an I/O operation. The central processor instructions that are 


designed to initialize the data for an I/O operation and to 


actually start the operation are: 


& 


fe) IO 
fe) IOLD 
fe) IOH 
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s For GCOS 6 system compatibility, the user should perform 
t IOLD instructions by using the ZIOLD subroutine instead of 
directly executing IOLD. 


These instructions, described in the Assembly Language 
manual and in the Honeywell Level 6 Minicomputer Handbook, can 
define all required information about an I/O operation. After 
I/O completion they can be used for input status to verify the 
results of the I/O operation. Some output and input functions 
that can be performed with these instructions are shown below. 


Instruction Function Description 
IO Output-interrupt control Set interrupt level 


for the device. 


TO Input device id Read the device id 
for the device. 


ITO Input status Test the state of 
the device. 


IO Output configuration Define operation 
explicitly (for 
disk, this defines 
track and sector 
number of the I/O 
operation). 


TO Output task Task defines the 
operation (1.e., 
seek, read, write 


aiaesa 


IO Input range Get the residual 
range (1.e., number 
of bytes not trans- 
ferred but request-— 
ed in the IOLD in- 
struction in 
ZIOLD). 


Note that every device type has different requirements as to 
which functions are necessary to Start an I/O operation. For 
example, the card reader has only one operation (i1.e., read); so 
the IOLD (output address and range) actually initiates the I/O, 
and there is no I/O output task command. 
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To start a disk I/O operation, the Sequence would be: 


Output configuration (Define sector and track) 

Output address and range (Use ZIOLD Subroutine) 

Output task (Define operation and start I/0) 
Input status (Check results) 
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APPENDIX C 


SUMMARY OF REGISTER CONTENTS FOR SYSTEM 


Table C-1 lists the register contents 


cution of the system service macro calls. 
macro calls do not affect registers, these 


SERVICE MACRO CALLS 


before and after exe- 
Since data structure 
are not listed. 


The table is arranged in function code sequence. 


CBO08 
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mm 


Table C-l. Macro Calls, Function Codes, and Register Contents 


Contents Before Execution Contents Returned 
i I SM 


Request and Return Functions 


SWAITL 01/01 Wait Status Wait ‘Address 
list list RB 
address address 


scantestani rine 


routine 
address 
- tf a an 
js | ovo sear joo 
sear 

SRBALD 01/07 Status | oe i 
routine 
address 


Pays ica? I/O Functions 


SROIO 02/00 Address || Status Address 
a on 


| sospy 02/02 | status | caw | 


cn a 
[soe [rane [ww | [| ine om 


SELST 02/05 Device | User log || Status 
name table 
address address 


Terminate |RB 
routine 
address 


\ 


Q 
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Table C-1l (cont). Macro Calls, Function Codes, 
and Register Contents 


‘Contents Before Execution Contents Returned 


Physical I/O Functions (cont) 


SELEX 02/07 Dev ice User log]||Status 
name table 
address address 
SELGCT 02/08 Device User log} |Status 
name table 
address address 
SELEND 02/09 Device User log||Status 
name table 
address address 
Memory Allocation Functions 
04/02 Return Size Size Status Size Size Address 
conditio memory 
04/03 a a ‘ati | a ie 
bag 
04/04 Address Status 
memory 
tail Size Size Address Status Size Size Address 
memory memory 
SSTMP ial Pool id Status {| Memory Memory Memory 
(percent) (words) (words) 


Address peste oe 
CRB 
CRB 


SSUS PN 05/02 Internal Internal Status 
value value 
[sm om ie 
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Table C-l (cont). Macro Calls, Function: Codes, ‘ 
and Register Contents 


Contents Before Execution Contents Returned 


Date/Time Functions 


Internal date/time . 


SEXTDT 05/04 Receiving}iStatus | Internal date/time Receiving 
field field 
address address 

SEXTIM 05/05 Receiving}iStatus | Internal date/time Receiving 
field field 
address address 


SINDIM Internal date/time ne External |j/Status External ae 
Semaphore Functions 


R5=size date/time date/time 
address 
SROSM 06/00 Address |/Status Address 
SRB SRB 
SCNSRQ 06/01 Address |/Status Address 
— a 


} seven a | raentigier] | )  TPstatus | | taentifier| | 


Overlay Handling Functions 
SOVE XC 07/00 Overlay Offset Base Status 
id address 


on .ae Overlay Base Status | Overlay Offset Base 
id address id address 

07 /03 rele Status | Overlay Offset Size Base 
status address 


SOVRSV 07/05 overlay Offset Overlay |jStatus | Overlay Overlay 
area id area 
table table 
address address 


Internal date/time 


Internal date/time 
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Macro Call 


SOVRLS 


SOVRCL 


SCROAT 


SUSIN 


SUSOUT 


SEROUT 


Lal 
B 


SNUIN 


SNUOUT 


sf 
a fod 


Rl 


07/06 


07/07 


07/0A 


07/0C 


08/00 
08/01 
08/02 
08/03 


08/04 


08/05 


Table C-l 


Contents Before Execution 


$B5 = Return point address 


(cont). 


Macro Calls, 


and Register Contents 


Function Codes, 


Contents Returned 


=e |e _.@ le (mje [* |» [~~ [« [= [a 


Overlay Offset 
id 


Size of 
overlay 
area entry 


Overlay 
id 


Number of 
entries 

in overlay 
area 


Request 


block 
address 


Address 
record 


Address 
record 
area 


Address 


record 


Address 
pathname 


Address 
pathname 


Code 
0006 


Overlay 
id 


Actual 
size of 
overlay 
area 


Offset 


Actual 
size of 
entries 
in 


overlay 
area 


ry 
= 
~ 
@ 


Request 
block 
address 


Overlay 
area 
table 
address 


Address 
record 
area 


Address 


record 
area 


Address 
record 
area 


Address 


record 
area 


Address 
pathname 


Address 
pathname 


80d0 


Table C-1l1 (cont). Macro Calls, Function Codes, 
and Register Contents 


Contents Before Execution | Contents Returned 


Operator Interface Functions 


SOPMSG © 09/00 Address || Status Address 
IORB IORB 

SOPRSP 09/01 Address |} Status Address 
IORB input 
list IORB 


a one { Toe PP 
C7 A, RT (SI (A ee ee a 


Trap Handling Functions 


STRPHD 0A/00 Address || Status 
handler 
SENTRP 0A/01 Trap [eee Trap 
number number 
SDSTRP 0A/02 Trap Status | Trap. 
number number 


External Switch Functions 


— em] of ff 
_ oS Pm] of oF 
_ Att tt 


Task Control Functions 


TRB 


SCANRQ 0Cc/01 Status Request 
block 
address 


Value 
switch 
word 


Request 
block 


address 
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Table C-l (cont). Macro Calls, Function Codes, 
and Register Contents 


Contents Before Execution Contents Returned 


Sen eae 


Task Control Functions (cont.) 
SCRTSK 0C/02 Level Address 
start 


LRN 

SCRTSK 0c /03 Level Address Status LRN 
root 
name 


cs 0C/05 Level Address | Address || Status 
root TRB 
name 

SSPTSK 0C/06 Level Address ee Status 
Start 


SCMDLN 0C/08 Size Address Status Address 
command 2 
line 

ar 0C/13 FIB Status 
address 


Task Group Control Functions 


SROGRP 0D /00 Group B5 = Address fixed Address Status 
id parameter block argument 
list 


SCRGRP CD/03 oe LRN LFN Address Status | Group 
root id 
name 

R4 = Memory pool id 
R5 = prises level 


id 


- : [Raed ak — PTT 
id id 


ae 


root argument 
name list 

Address fixed parameter block 

Memory pool id 

Priority level 
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Table C-l (cont). 


Contents Before Execution 


Task Group Control Functions (cont.) 


Macro Calls, Function Codes, 
and Register Contents 


Contents Returned 


atone! a Oe A A | 


id 
SSUS PG 0D/C8 Group 

id 

an 


} svproo Fopyoe_| 


_ “ == 


Batch Functions 


= Address ae 
ae block 


Frror Handling Function 


pee 


Address Status 
argument 
list 


SRPTER OF/00 


se [oe 


Status Code 
R2 = Component error code 
-B3 = Expansion text address . 


File Management Functions 


- Pf ff 


SDSF IL 10/15 
SCTF IL 10/20 


— 


Address Status 
argument 
.structure 


Address Status 
argument 
structure 
Address Status 
argument 
structure 
Address Status 
argument 
structure 


_ 
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Table C-l (cont). 


Contents Before Execution 


File Management Functions (cont) 


Macro Calls, Function Codes, 
and Register Contents 


Contents Returned 


desta eee ee ee 


a 
ba a 
ba a 
a a 


Address Status 
argument 
structure 
Address Status 
argument 
structure 
Address Status 
argument 
structure 
Address Status 
argument 
structure 


i 10/50, Address -_ 
aes FIB 


— TT 


| 10/62 Address 
FIB 

a 10/63 Address 
FIB 


aaa (ot fd 
— Poff dL 


— Pf ft 


Address Status. 
FIB 


Address Status 

argument 

structure 

wT Uk lt CC 
——E 


Address Status 
argument 
structure 
Address Status 
argument 
structure 
Address Status 
argument 
structure 


OT-O 


80d) 


Table C-1 (cont). Macro Calls, Function Codes, 
and Register Contents 


Contents Before Execution Contents Returned 


eee NG SC CC 


File Management Functions (cont) 


SRLDIR —«+|:10/A5 Address j|/Status 
argument 
structure 

SCWDIR 10/B0 Address’ ||Status 
argument 
structure 

SGWDIR 10/c0 Address Status 
argument 
structure 

SXPATH 10/00 Address Status 
argument 
structure 


Data Management Functions 


Address Status 

FIB 
Address Status 
FIB 


SRDREC 


| ae ~~ 
| ae 
Address Status 
FIB 


Storage Management Functions 


Address Status 
FIB 


a oa 
a 

Address Status 

FIB 


: 
Cc 
A 
ly 
= 
N 
2 


Tt-o 
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Table C-l (cont). 


Contents Before Fxecution 


Macro Calls, Function Codes, 
and Register Contents 


| Contents Returned 


Identification and Information Functions 


eoonte [ew |» Je eee» |» |» [» 


“ tt 
~ ~ Pf fd 


— - Pot ft 


Intergroup Message Facility Functions 


a Pf ft 
7 Pf fd 


Address 


receiving 
field 


Address 
receiving 
field 


Status 


Address 
receiving 
field 


receiving 
field 
Address Status 
receiving 

field 


Address 
receiving 
field 


Status 


Address 
receiving 
field 


Status 


Address 


Address Status 
receiving 
field 


Request Status 
block 

address 

Request Status 
block 

address 


Address 
receiving 
field 


Address 


receiving 
field 


Address 
receiving 
field 


Address 
receiving 
Address 


task group 


Request 
block 
address 


Request 
block 
address 


fT-O 
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Table C-1 (cont). Macro Calls, Function Codes, 
and Register Contents 


Contents Before Execution Contents Returned 


re aed a See oe ee eee 


Intergroup Message Facility Functions (cont) 


SMRECV 15/03 Request j|Status Request 
‘block block 
address address 


Request 
block 
address 


15/04 Request 
block 
request — 

SMSEND 15/05 Request 
block 
address 

- | ¢ i 3: 


User Terminal Functions 


_ Ff | 
_ po. ee 


Request 


block 
address 


Request 


block 
address 


Request 
block 
address 


Request 
block 
address 


Release Status . 
status é 

code 

Peep tf] Ew 


Address | Address 
device telephone 
pathname | number 


sets, 


APPENDIX D 


ASCII AND EBCDIC CHARACTER SETS 


Tables D-l and D-2 illustrate the ASCII and EBCDIC character 


respectively. 


In addition to the ASCII characters, 


Table 


D-1 shows the hexadecimal equivalents; Table D-2 shows the binary 
and hexadecimal eguivalents of the EBCDIC character set. 


graphic characters 


Following are lists of the control characters and Special 


CONTROL CHARACTERS 


ACK 
BEL 
BS 
BYP 
CAN 
CC 
CR 
CUl 
CU2 
CU 3 
DC 1 
DC 2 
DC 3 
DC 4 
DEL 
DLE 
DS 
EM 
ENQ 
EO 
EOT 
ESC 
ETB 
ETX 
FF 
FS 


Acknowledge 
Bell 

Backspace 
Bypass 

Cancel 

Cursor Control 
Carriage Return 
Customer Use 1 
Customer Use 2 
Customer Use 3 
Device Control 
Device Control 
Device Control 
Device Control 
Delete 

Data Link Escape 

Digit Select 

End of Medium 

Enquiry 

Eight Ones 

End of Transmission 
Escape 

End of Transmission Block 
End of Text 

Form Feed 

Field Separator 


WM GW NN Fe 


that appear in the two tables: 


Graphic Escape 

Group Separator 

Horizontal Tab 

Interchange File Separator 
Interchange Group Separator 
Idle | 
Interchange Record Separator 
Interchange Unit Separator 
Lowercase 

Line Feed 

Negative Acknowledgment 
New Line 

Null 

Punch Off 

Punch On 

Restore 

Reverse Line Feed 

Reader Stop 

Shift In 

Set Mode 

Start of Manual Message 
Shift Out 

Start of Heading 

Start of Significance 
Space 

Start of Text 
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CONTROL CHARACTERS (cont) 


SUB Substitute 
SYN Synchronous Idle 


TM Tape Mark 
SPECIAL GRAPHIC CHARACTERS 
Cent Sign 


Less-than Sign 
Left Parenthesis 
Plus Sign 

Logical OR 
Ampersand _ 
Exclamation Point 
Dollar Sign 
Asterisk 

Right Parenthesis 
Semicolon 

Logical NOT 

Minus Sign 

Slash 

Vertical Line 
Comma 

Percent 
Underscore 
Circumflex 


gos —N Los S ame m--+ Ane oO 


Table D-l. 


Period, Decimal Point 


UC 
US 
VT 


eV y 


= (S) =H eo 


~ 


Hoa Kto- 2 


las 
Be 
PD 
rey 

O 


Uppercase 


Unit Separator 
Vertical Tab 


Greater-than Sign 
Question Mark 
Grave Accent 
Colon 

Number Sign 

At Sign 

Prime, Apostrophe 
Equal Sign 
Quotation Mark 
Tilde 

Opening Brace 
Hook 

Fork 

Closing Brace 
Reverse Slant 
Chair 


Long Vertical Mark 


Opening Bracket 
Closing Bracket 


ASCII/Hexadecimal Equivalents 
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EBCDIC/Hexadecimal/Binary Equivalents 


Table D-2, 


So 

n 

= 

= 

—_ 

7) 

io) 

Qu 

a ee 

xy 
= : 
Lh, aintrt 1 4 ™ mo 
: | 
2fel>] -[-[efelefeb ls] |] | | 
a) os 

s[|=f-|=[efele[+[fl-f | fal BL 


First Hexadecimal Digit 


\Bit Positions 2,3 


lahat Wiviileleleidatel Fe) 4 

lela) |] ET TET | de EeehE 
of 

z 6/5 2/s/2) |s 

N C =) 

ne. ze x ~ilD]w UIAIsZz Nn 
be J 

S/u/2|y 2/3] |Zl€ lz 

Fp) YN (Fa) we > 

er 3 ic minim] w nm 1 a [<i[a 


arom rvs] =| [> [|e [fol e[o[<[[e [> fo 
oe s/sl2/=isisl2e/=/slslelzls|s 
L°9°S pr suonisog nat] S| StS; st< —}—|]S/ S10 7 b= 
S151 6 Lette eolol{=j{={[= —{= 


“This character is not supported in the 2780 character set. 
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ABORT 
ABORT GROUP REQUEST (SABGRQ) 
MACRO CALL, 5-4 
ABORT GROUP (SABGRP) 
MACRO CALL, 5-2 


ACCEPT 
MESSAGE GROUP ACCEPT (SMACPT) 
MACRO CALL, 5-172 


ACCEPTOR 
MESSAGE GROUP ACCEPTOR GROUP, 
5-172, 5-189 


ACCOUNT 
ACCOUNT IDENTIFICATION (SACTID) 
MACRO CALL, 5-6 


ACTID 
ACCOUNT IDENTIFICATION (SACTID) 
MACRO CALL 5-6 


ACTIVATE 
ACTIVATE GROUP (SACTVG) 
MACRO CALL, 5-8 


ADDRESS 
RETURN REQUEST BLOCK ADDRESS 
(SRBADD) MACRO CALL, 5-316 
USER-DRIVER OUTPUT ADDRESS AND 
RANGE (ZIOLD) SUBROUTINE, B-6 


ADDRESSING 
ADDRESSING CONVENTIONS, 1-3 


ALLOCATE 
INITIALIZE, ALLOCATE GROUP DATA 
STRUCTURES, 5-57 
INITIALIZE, ALLOCATE TASK DATA 
STRUCTURES, 5-64 


ALLOCATION, MEMORY 
MONITOR SERVICE FUNCTIONS, MEMORY 
ALLOCATION, 2-4 


APPEND CHARACTERS 
APPEND ASCII CHARACTERS TO 
PATHNAME, 5-133 


AREA 
CONTENTS OF TRAP-RELATED MEMORY 
AREAS, 772 
POINTER TO NEXT TRAP SAVE AREA 
(NATSAP), 7-5 
TRAP INTERRUPT SAVE AREA 
(ISA), 7-6 
TRAP SAVE AREAS, 7-6 


ARGUMENT VALUES FOR MESSAGE GROUP 
MACRO CALLS 
ARGUMENT VALUES FOR $MGCRB 
MACRO CALL (TBL), 5-176 
ARGUMENT VALUES FOR $MGIRB 
MACRO CALL (TBL), 5-185 


INDEX 


‘ARGUMENT VALUES FOR MESSAGE GROUP 
MACRO CALLS (CONT) 


ARGUMENT VALUES FOR SMGRRB 
MACRO CALL (TBL), 5-197 

MGCRB ARGUMENT VALUES FOR SMRFCV 
MACRO CALL (‘i'BL), 5-193 

MGCRB ARGUMENT VALUES FOR SMSEND 
MACRO CALL ‘TBL), 5-202 

MGIRB ARGUMEN? VALUES FOR SMACPT 
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